This is SchurRings.info, produced by Macaulay2, version 1.26.06

SchurRings -- Rings representing irreducible representations of general linear or symmetric groups
**************************************************************************************************

Description
===========

This package makes computations in the representation rings of general linear
groups and symmetric groups possible.

Given a positive integer n we may define a polynomial ring in n variables over
an arbitrary base ring , whose monomials correspond to the irreducible
representations of GL(n), and where multiplication is given by the
decomposition of the tensor product of representations. We create such a ring
in Macaulay2 using the schurRing, function.

+------------------------------+
|i1 : S = schurRing(QQ,s,4)    |
|                              |
|o1 = S                        |
|                              |
|o1 : SchurRing                |
+------------------------------+
|i2 : R = schurRing(r,infinity)|
|                              |
|o2 = R                        |
|                              |
|o2 : SchurRing                |
+------------------------------+

Note that in the above, n is allowed to be equal to \infty. However, in this
version of the package, many of the features from the case n finite are missing
from the infinite case, so the user is advised to use large values for n as a
substitute, whenever necessary.

We determine the relative dimension of a SchurRing over its base using the
numgens (Macaulay2Doc), function:

+-------------------+
|i3 : numgens S     |
|                   |
|o3 = 4             |
+-------------------+
|i4 : numgens R     |
|                   |
|o4 = infinity      |
|                   |
|o4 : InfiniteNumber|
+-------------------+

For k\leq n, one may interpret the degree k homogeneous component of a
SchurRing, as the representation ring of the symmetric group S_k. In
this ring, the multiplication is different than the one in the representation
ring of GL(n). By default, the elements of a SchurRing, are
interpreted as (virtual) characters of a general linear group. This
interpretation is controlled by the option GroupActing,
whose default value is "GL". To indicate that the elements of a Schur ring
should be interpreted as characters of the symmetric group, one has to set the
option GroupActing, to "Sn".

+-------------------------------------------+
|i5 : Q = schurRing(q,4,GroupActing => "Sn")|
|                                           |
|o5 = Q                                     |
|                                           |
|o5 : SchurRing                             |
+-------------------------------------------+

A monomial in S represents the irreducible representation with a given highest
weight. The standard GL(4)-representation is

+------------+
|i6 : V = s_1|
|            |
|o6 = s      |
|      1     |
|            |
|o6 : S      |
+------------+

We may see the dimension of the corresponding irreducible representation using
dim (Macaulay2Doc),:

+----------+
|i7 : dim V|
|          |
|o7 = 4    |
+----------+

Multiplication of elements corresponds to tensor product of representations.
The value is computed using a variant of the Littlewood-Richardson rule.

+------------------------+
|i8 : V * V              |
|                        |
|o8 = s  + s             |
|      2    1,1          |
|                        |
|o8 : S                  |
+------------------------+
|i9 : V^3                |
|                        |
|o9 = s  + 2s    + s     |
|      3     2,1    1,1,1|
|                        |
|o9 : S                  |
+------------------------+

The third symmetric power of V is obtained by

+---------------+
|i10 : W = s_{3}|
|               |
|o10 = s        |
|       3       |
|               |
|o10 : S        |
+---------------+
|i11 : dim W    |
|               |
|o11 = 20       |
+---------------+

and the third exterior power of V can be obtained using

+-------------------+
|i12 : U = s_{1,1,1}|
|                   |
|o12 = s            |
|       1,1,1       |
|                   |
|o12 : S            |
+-------------------+
|i13 : dim U        |
|                   |
|o13 = 4            |
+-------------------+

Alternatively, one can use the functions symmetricPower (Macaulay2Doc),
and exteriorPower (Macaulay2Doc),:

+-----------------------------+
|i14 : W = symmetricPower(3,V)|
|                             |
|o14 = s                      |
|       3                     |
|                             |
|o14 : S                      |
+-----------------------------+
|i15 : U = exteriorPower(3,V) |
|                             |
|o15 = s                      |
|       1,1,1                 |
|                             |
|o15 : S                      |
+-----------------------------+

We can in fact take symmetric powers and exterior powers of any representation:

+-------------------------+
|i16 : exteriorPower(2,W) |
|                         |
|o16 = s    + s           |
|       5,1    3,3        |
|                         |
|o16 : S                  |
+-------------------------+
|i17 : symmetricPower(2,U)|
|                         |
|o17 = s                  |
|       2,2,2             |
|                         |
|o17 : S                  |
+-------------------------+

and compute even more general forms of plethysm,:

+-----------------------------------------------------------------------------+
|i18 : plethysm(W+U,W+U)                                                      |
|                                                                             |
|o18 = s  + s    + 2s      + 2s    + s      + 2s        + 2s      + 2s      + |
|       9    7,2     7,1,1     6,3    6,2,1     6,1,1,1     5,3,1     5,2,2   |
|      -----------------------------------------------------------------------|
|      3s        + 2s      + 2s        + 2s        + 2s      + 2s             |
|        5,2,1,1     4,4,1     4,3,1,1     4,2,2,1     3,3,3     3,2,2,2      |
|                                                                             |
|o18 : S                                                                      |
+-----------------------------------------------------------------------------+

Alternatively, we can use the binary operator @ (Macaulay2Doc), to
compute plethysm:

+-----------------------------------------------------------------------------+
|i19 : s_2 @ s_3                                                              |
|                                                                             |
|o19 = s  + s                                                                 |
|       6    4,2                                                              |
|                                                                             |
|o19 : S                                                                      |
+-----------------------------------------------------------------------------+
|i20 : (W+U) @ (W+U)                                                          |
|                                                                             |
|o20 = s  + s    + 2s      + 2s    + s      + 2s        + 2s      + 2s      + |
|       9    7,2     7,1,1     6,3    6,2,1     6,1,1,1     5,3,1     5,2,2   |
|      -----------------------------------------------------------------------|
|      3s        + 2s      + 2s        + 2s        + 2s      + 2s             |
|        5,2,1,1     4,4,1     4,3,1,1     4,2,2,1     3,3,3     3,2,2,2      |
|                                                                             |
|o20 : S                                                                      |
+-----------------------------------------------------------------------------+

All the above calculations assume that we're dealing with representations of
GL(4). But as symmetric functions of degree three, W and U, can be thought of
as characters of the symmetric group S_3. Let us first ``move'' these symmetric
functions into a Schur ring designed to deal with characters of symmetric
groups (like the ring Q defined above):

+-------------------+
|i21 : W' = toS(W,Q)|
|                   |
|o21 = q            |
|       3           |
|                   |
|o21 : Q            |
+-------------------+
|i22 : U' = toS(U,Q)|
|                   |
|o22 = q            |
|       1,1,1       |
|                   |
|o22 : Q            |
+-------------------+

Now W' corresponds to the trivial representation of S_3, and U' to the sign
representation. As such, we can tensor them together using the function
internalProduct, or the binary operator * (Macaulay2Doc).

+-------------+
|i23 : W' * U'|
|             |
|o23 = q      |
|       1,1,1 |
|             |
|o23 : Q      |
+-------------+

We can generate the class function corresponding to an S_n-representation,
using the function classFunction,:

+-----------------------------------+
|i24 : cfW = classFunction(W')      |
|                                   |
|o24 = ClassFunction{{1, 1, 1} => 1}|
|                    {2, 1} => 1    |
|                    {3} => 1       |
|                                   |
|o24 : ClassFunction                |
+-----------------------------------+
|i25 : cfU = classFunction(U')      |
|                                   |
|o25 = ClassFunction{{1, 1, 1} => 1}|
|                    {2, 1} => -1   |
|                    {3} => 1       |
|                                   |
|o25 : ClassFunction                |
+-----------------------------------+

We can multiply class functions together, and transform class functions into
symmetric functions using the function symmetricFunction,:

+-----------------------------------+
|i26 : cfWU = cfW * cfU             |
|                                   |
|o26 = ClassFunction{{1, 1, 1} => 1}|
|                    {2, 1} => -1   |
|                    {3} => 1       |
|                                   |
|o26 : ClassFunction                |
+-----------------------------------+
|i27 : symmetricFunction(cfWU,Q)    |
|                                   |
|o27 = q                            |
|       1,1,1                       |
|                                   |
|o27 : Q                            |
+-----------------------------------+

The result of the previous computation is of course the same as that of taking
the product of W' and U'.

We can take exterior and symmetric powers of S_n-representations, just as for
GL-modules (compare to o16 and o17):

+--------------------------+
|i28 : exteriorPower(2,W') |
|                          |
|o28 = 0                   |
|                          |
|o28 : Q                   |
+--------------------------+
|i29 : symmetricPower(2,U')|
|                          |
|o29 = q                   |
|       3                  |
|                          |
|o29 : Q                   |
+--------------------------+

We can write any symmetric function in terms of the standard e- (elementary
symmetric), h- (complete) and p- (power sum) bases, using the functions
toE, toH, toP, respectively:

+--------------------------------+
|i30 : toE U                     |
|                                |
|o30 = e                         |
|       3                        |
|                                |
|o30 : QQ[e ..e , p ..p , h ..h ]|
|          1   4   1   4   1   4 |
+--------------------------------+
|i31 : toH U                     |
|                                |
|       3                        |
|o31 = h  - 2h h  + h            |
|       1     1 2    3           |
|                                |
|o31 : QQ[e ..e , p ..p , h ..h ]|
|          1   4   1   4   1   4 |
+--------------------------------+
|i32 : toP W                     |
|                                |
|      1 3   1       1           |
|o32 = -p  + -p p  + -p          |
|      6 1   2 1 2   3 3         |
|                                |
|o32 : QQ[e ..e , p ..p , h ..h ]|
|          1   4   1   4   1   4 |
+--------------------------------+

These expressions live in the Symmetric ring associated to S, which can be
obtained using the function symmetricRing,:

+-------------------------+
|i33 : A = symmetricRing S|
|                         |
|o33 = A                  |
|                         |
|o33 : PolynomialRing     |
+-------------------------+

Similarly, any Symmetric ring has a Schur ring attached to it, which can be
obtained using the function schurRing,:

+-----------------------+
|i34 : schurRing A === S|
|                       |
|o34 = true             |
+-----------------------+

We construct tensor products of Schur rings iteratively by allowing Schur rings
over base rings that are also Schur rings:

+--------------------------+
|i35 : T = schurRing(S,t,3)|
|                          |
|o35 = T                   |
|                          |
|o35 : SchurRing           |
+--------------------------+

The Schur ring T can thus be thought of as the representation ring of
GL(V)\times GL(V'), where V is as before a vector space of dimension 4, and V'
is a vector space of dimension 3. The representation corresponding to V' is

+--------------+
|i36 : V' = t_1|
|              |
|o36 = t       |
|       1      |
|              |
|o36 : T       |
+--------------+

The function schurLevel, indicates the number of Schur rings
that have been tensored together to obtain any given ring:

+-------------------+
|i37 : schurLevel T |
|                   |
|o37 = 2            |
+-------------------+
|i38 : schurLevel S |
|                   |
|o38 = 1            |
+-------------------+
|i39 : schurLevel QQ|
|                   |
|o39 = 0            |
+-------------------+

We can now check Cauchy's formula for decomposing symmetric/exterior powers of
a tensor product:

+------------------------------------+
|i40 : symmetricPower(3,V*V')        |
|                                    |
|o40 = s t  + s   t    + s     t     |
|       3 3    2,1 2,1    1,1,1 1,1,1|
|                                    |
|o40 : T                             |
+------------------------------------+
|i41 : exteriorPower(3,V*V')         |
|                                    |
|o41 = s     t  + s   t    + s t     |
|       1,1,1 3    2,1 2,1    3 1,1,1|
|                                    |
|o41 : T                             |
+------------------------------------+

We end with the computation of the GL(n)- and S_n-equivariant resolutions of
the residue field of a polynomial ring in n variables. The function that does
this calculation, see schurResolution, is based on an
empirical method, which gives the correct answer in surprisingly many
situations.

In the GL(n) situation, we are resolving the residue field which as a
representation has character 1_S. The space of linear forms in the polynomial
ring considered as a GL-representation has character V = s_1.

+--------------------------------------------------------------------------+
|i42 : n = 4                                                               |
|                                                                          |
|o42 = 4                                                                   |
+--------------------------------------------------------------------------+
|i43 : M = {1_S}                                                           |
|                                                                          |
|o43 = {s  }                                                               |
|        ()                                                                |
|                                                                          |
|o43 : List                                                                |
+--------------------------------------------------------------------------+
|i44 : schurResolution(V,M,DegreeLimit => n)                               |
|                                                                          |
|o44 = {{(0, s  )}, {(1, s )}, {(2, s   )}, {(3, s     )}, {(4, s       )}}|
|             ()          1          1,1          1,1,1          1,1,1,1   |
|                                                                          |
|o44 : List                                                                |
+--------------------------------------------------------------------------+

Not surprisingly, the syzygy modules are generated by the exterior powers of V.

The residue field as a representation of the symmetric group S_n has character
s_n. The space of linear forms in the polynomial ring considered as an
S_n-representation coincides with the permutation representation of S_n, thus
has character s_n + s_{n-1,1}.

+-----------------------------------------------------------------------------+
|i45 : rep = q_n + q_(n-1,1)                                                  |
|                                                                             |
|o45 = q  + q                                                                 |
|       4    3,1                                                              |
|                                                                             |
|o45 : Q                                                                      |
+-----------------------------------------------------------------------------+
|i46 : M = {q_n}                                                              |
|                                                                             |
|o46 = {q }                                                                   |
|        4                                                                    |
|                                                                             |
|o46 : List                                                                   |
+-----------------------------------------------------------------------------+
|i47 : sR = schurResolution(rep,M,DegreeLimit => n)                           |
|                                                                             |
|o47 = {{(0, q )}, {(1, q  + q   )}, {(2, q    + q     )}, {(3, q      +      |
|             4          4    3,1          3,1    2,1,1          2,1,1        |
|      -----------------------------------------------------------------------|
|      q       )}, {(4, q       )}}                                           |
|       1,1,1,1          1,1,1,1                                              |
|                                                                             |
|o47 : List                                                                   |
+-----------------------------------------------------------------------------+

We can check that the second syzygy module is generated by the second exterior
power of the permutation representation.

+-----------------------------------+
|i48 : eP2rep = exteriorPower(2,rep)|
|                                   |
|o48 = q    + q                     |
|  3,1    2,1,1                     |
|                                   |
|o48 : Q                            |
+-----------------------------------+
|i49 : eP2rep == last sR#2#0        |
|                                   |
|o49 = true                         |
+-----------------------------------+

Variant character rings.  Beyond the general linear and symmetric groups, the
package supports several other families of representation rings.  All of them
are realized as SchurRing,s, with behavior controlled by the
option GroupActing, (and, for basis conversions, see
Basis).  The current values are:

$\bullet$ "GL" (default): polynomial representations of $GL_n$, with basis the
Schur functions $s_\lambda$ and the Littlewood-Richardson product.

$\bullet$ "Sn": the representation ring of the symmetric group $S_n$, with
basis indexed by partitions and product the internal product (Kronecker product
of $S_n$-characters).  See internalProduct.

$\bullet$ "Sp": the (universal or finite-rank) character ring of the symplectic
groups, with basis $sp_\lambda$ and product the Newell-Littlewood product.  See
toSp.

$\bullet$ "O": the (universal or finite-rank) character ring of the orthogonal
groups, with basis $o_\lambda$.  The finite-rank ring distinguishes type $B$
and type $D$ via the option OddOrEven.  See toO.

$\bullet$ "RatGL": the ring of rational (i.e. finite-dim'l) representations of
$GL_n$, whose irreducibles are indexed by bipartitions $(\alpha,\beta)$.  See
toRatGL.

$\bullet$ "SL": the ring of polynomial representations of $SL_n$ (rows of
length $n$ are killed).

Orthogonally, the option Basis, $=>$ "Monomial" replaces the Schur
basis with the monomial symmetric functions $m_\lambda$; multiplication is
implemented by round-tripping through the Schur basis using Kostka numbers
(see kostkaNumber, toM).

+--------------------------------------------------------+
|i50 : Sp = schurRing(QQ, sp, 3, GroupActing => "Sp");   |
+--------------------------------------------------------+
|i51 : sp_{1} * sp_{1}                                   |
|                                                        |
|o51 = sp  + sp    + sp                                  |
|        2     1,1     ()                                |
|                                                        |
|o51 : Sp                                                |
+--------------------------------------------------------+
|i52 : O = schurRing(QQ, o, 4, GroupActing => "O");      |
+--------------------------------------------------------+
|i53 : o_{1} * o_{2}                                     |
|                                                        |
|o53 = o  + o    + o                                     |
|       3    2,1    1                                    |
|                                                        |
|o53 : O                                                 |
+--------------------------------------------------------+
|i54 : Rat = schurRing(QQ, r, 3, GroupActing => "RatGL");|
+--------------------------------------------------------+
|i55 : r_{{1},{1}} * r_{{1},{}}                          |
|                                                        |
|o55 = r           + r              + r                  |
|       {{2}, {1}}    {{1, 1}, {1}}    {{1}, {}}         |
|                                                        |
|o55 : Rat                                               |
+--------------------------------------------------------+
|i56 : Mon = schurRing(QQ, m, 4, Basis => "Monomial");   |
+--------------------------------------------------------+
|i57 : m_{1} * m_{1}                                     |
|                                                        |
|o57 = m  + 2m                                           |
|       2     1,1                                        |
|                                                        |
|o57 : Mon                                               |
+--------------------------------------------------------+

Stable vs.\ finite-rank rings.  Each of the above flavors comes in two sizes.
Passing a positive integer n to schurRing, constructs the
finite-rank ring, where partitions are restricted in length (to $n$ for GL/Sn
and to the appropriate rank for Sp/O/RatGL) and the Sam-Snowden-Weyman
modification rules are applied automatically.  Passing infinity instead
constructs the stable (universal) ring: a polynomial ring with countably many
generators, one for each partition, on which all operations are performed
without modification.  This is the ring of universal characters of
Koike--Terada, — a single computation that specializes to every
finite rank.

+----------------------------------------------------------------+
|i58 : StabGL = schurRing(QQ, sg, infinity);                     |
+----------------------------------------------------------------+
|i59 : StabSp = schurRing(QQ, tp, infinity, GroupActing => "Sp");|
+----------------------------------------------------------------+
|i60 : tp_{1,1} * tp_{1,1}                                       |
|                                                                |
|o60 = tp    + tp      + tp  + tp        + tp    + tp            |
|        2,2     2,1,1     2     1,1,1,1     1,1     ()          |
|                                                                |
|o60 : StabSp                                                    |
+----------------------------------------------------------------+

Having computed in the stable ring, one can specialize, to a
finite rank at the end.  The modification rule drops or re-signs any partition
that exceeds the target rank.

+--------------------------------------------------------------+
|i61 : f = tp_{1,1} * tp_{1,1};                                |
+--------------------------------------------------------------+
|i62 : specialize(f, 2)     -- inside Sp(4)                    |
|                                                              |
|o62 = spfin2    + spfin2  + spfin2    + spfin2                |
|            2,2         2         1,1         ()              |
|                                                              |
|o62 : schurRing (QQ, spfin2, 2)                               |
+--------------------------------------------------------------+
|i63 : specialize(f, 3)     -- inside Sp(6)                    |
|                                                              |
|o63 = spfin3    + spfin3      + spfin3  + spfin3    + spfin3  |
|            2,2         2,1,1         2         1,1         ()|
|                                                              |
|o63 : schurRing (QQ, spfin3, 3)                               |
+--------------------------------------------------------------+

Conversions between variants.  Every basis conversion is reversible and
functorial.  The table below summarizes the user-level commands for moving
between them:

$\bullet$ See toS, toGL,: to the plain Schur (GL) basis.

$\bullet$ See toE, toH, toP,: to the
$e/h/p$-basis (lives in the associated symmetricRing).

$\bullet$ See toSymm,: inverse of toS,; pushes a
Schur-basis element into the symmetric ring.

$\bullet$ See toM,: to the monomial basis.

$\bullet$ See toSp, toO,: to the symplectic or orthogonal
character basis, via the inverse Koike branching formulas.

$\bullet$ See toRatGL,: embeds a (polynomial) GL character into the
ring of rational GL characters.

$\bullet$ See toSn,: carries coefficient data from a GL-style ring into
an Sn-style ring (same partition labels, different product).

$\bullet$ See convert,: a universal dispatcher — given any source
and any target, it picks the right converter.

$\bullet$ See specialize,: stable ring $\to$ finite-rank ring,
for any variant (applies the appropriate modification rule).

$\bullet$ See branch,: restricts a Schur, Sp, or O character along
the diagonal of a product of two classical groups.

+-----------------------------------------------------+
|i64 : S = schurRing(QQ, s, 5);                       |
+-----------------------------------------------------+
|i65 : Sp = schurRing(QQ, sp, 2, GroupActing => "Sp");|
+-----------------------------------------------------+
|i66 : convert(s_{2,1}, Sp)                           |
|                                                     |
|o66 = sp    + sp                                     |
|        2,1     1                                    |
|                                                     |
|o66 : Sp                                             |
+-----------------------------------------------------+
|i67 : convert(oo, S)                                 |
|                                                     |
|o67 = s                                              |
|       2,1                                           |
|                                                     |
|o67 : S                                              |
+-----------------------------------------------------+

The compatibility of these conversions can be verified against the
Newell-Littlewood product directly.  For instance, in the stable symplectic
ring, $sp_{(1)}^2 = sp_{(2)} + sp_{(1,1)} + 1$; equivalently, $(s_{(1)})^2 =
s_{(2)} + s_{(1,1)}$, and expanding each Schur function in the Sp basis via
toSp, and adding yields the same element.

Mathematical background.  We collect some pointers for readers who wish to
consult the original sources.

$\bullet$ Schur-Weyl duality states that the group algebras of $GL_n$ and $S_d$
act on $V^{\otimes d}$ with mutually centralizing images, so the decomposition
of $V^{\otimes d}$ as a $GL_n \times S_d$-module provides a bijection between
polynomial representations of $GL_n$ of degree $d$ and representations of
$S_d$.  The toSn, / see toGL, pair is the computational
realization of this bijection.

$\bullet$ The Frobenius characteristic identifies the representation ring of
$S_n$ with the degree-$n$ component of the ring of symmetric functions.  Under
this isomorphism, the character of a virtual representation corresponds to a
symmetric function, and the internal product of characters to a product
expressible in the power-sum basis.  See classFunction,
and symmetricFunction.

$\bullet$ The Koike-Terada universal characters provide a single family of
symmetric functions whose specializations at $n$ variables recover the
irreducible characters of $Sp(2n)$ (or $O(n)$) for every $n$.  Equivalently,
the stable Sp/O character rings form a purely combinatorial object, and the
Sam-Snowden-Weyman modification rule tells us how to specialize to finite rank.

$\bullet$ The Newell-Littlewood product is the multiplication in the stable
Sp/O ring, expressed as a Littlewood-Richardson-like sum: $$sp_\mu \cdot sp_\nu
= \sum_{\alpha,\beta,\gamma} c^\mu_{\alpha,\beta}\, c^\nu_{\alpha,\gamma}\,
sp_{\beta\gamma},$$ where $c^\lambda_{\mu\nu}$ are the Littlewood-Richardson
coefficients.  The analogous formula holds for $o$.  Our implementation
replaces this with the equivalent route (Schur basis, multiply, back to Sp/O
via toSp,/see toO), which is both faster and easier to
certify.

$\bullet$ King branching formulas describe the restriction of a character of a
classical group to a two-factor subgroup. See branch.

$\bullet$ Plethysm $f[g]$ encodes composition of Schur functors: $f[g]$ is the
character of the $GL(V)$-representation obtained by applying the functor with
character $f$ to the representation with character $g$.  Our implementation
agrees with the classical definition on power-sum generators:
$p_n[g(x_1,x_2,\dots)] = g(x_1^n, x_2^n, \dots)$.  See plethysm.

References.

$\bullet$ I.\ G.\ Macdonald, Symmetric Functions and Hall Polynomials, 2nd ed.,
Oxford University Press, 1995.

$\bullet$ W.\ Fulton, Young Tableaux, LMSST 35, Cambridge University Press,
1997.

$\bullet$ W.\ Fulton and J.\ Harris, Representation Theory. A First Course, GTM
129, Springer, 1991.

$\bullet$ R.\ P.\ Stanley, Enumerative Combinatorics, Vol.\ 2, Cambridge
University Press, 1999.

$\bullet$ B.\ E.\ Sagan, The Symmetric Group.  Representations, Combinatorial
Algorithms, and Symmetric Functions, 2nd ed., GTM 203, Springer, 2001.

$\bullet$ J.\ Weyman, Cohomology of Vector Bundles and Syzygies, Cambridge
Tracts in Math.\ 149, 2003.

$\bullet$ K.\ Koike, On the decomposition of tensor products of the
representations of classical groups: by means of universal characters, Adv.\
Math.\ 74 (1989), 57–86.

$\bullet$ K.\ Koike and I.\ Terada, Young-diagrammatic methods for the
representation theory of the classical groups of type $B_n$, $C_n$, $D_n$, J.\
Algebra 107 (1987), 466–511.

$\bullet$ R.\ C.\ King, Branching rules for classical Lie groups using tensor
and spinor methods, J.\ Phys.\ A 8 (1975), 429–449.

$\bullet$ S.\ V.\ Sam and A.\ Snowden, Introduction to twisted commutative
algebras, arXiv:1209.5122 (2012).

$\bullet$ S.\ V.\ Sam and A.\ Snowden, Stability patterns in representation
theory, Forum Math.\ Sigma 3 (2015), e11.

$\bullet$ S.\ V.\ Sam, A.\ Snowden, and J.\ Weyman, Homology of Littlewood
complexes, Selecta Math.\ (N.S.) 19 (2013), 655–698.

Authors
=======

  * Michael Stillman (see http://www.math.cornell.edu/~mike/ )
    <mike@math.cornell.edu>
  * Hal Schenck
  * Claudiu Raicu (see http://math.berkeley.edu/~claudiu/ ) <craicu@nd.edu>
  * Keller VandeBogert (see https://sites.google.com/view/kellervandebogert/
    home ) <keller.v@uky.edu>

Version
=======

This documentation describes version 2.0 of SchurRings, released April 17,
2026.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{SchurRingsSource,                                                      |
|  title = {{SchurRings: representation rings of general linear groups and    |
|  author = {Michael Stillman and Hal Schenck and Claudiu Raicu and Keller    |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages   |
|}                                                                            |
|-----------------------------------------------------------------------------|
|of symmetric groups. Version~2.0}},                                          |
|VandeBogert},                                                                |
|                                                                             |
|}}                                                                           |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * ClassFunction -- The class of all Class functions
      * SchurRing -- The class of all Schur rings
      * SchurRingElement -- A type describing elements
        of a SchurRing
      * SchurRingIndexedVariableTable
  * Functions and commands
      * branch -- Restrict a Schur, Sp, or O character along a
        two-factor subgroup
      * centralizerSize -- Size of the centralizer of a
        permutation
      * classFunction -- Converts symmetric function to
        class function
      * convert -- Universal dispatcher for converting between
        Schur ring flavors
      * internalProduct -- Internal product of
        symmetric functions/class functions
      * jacobiTrudi -- Jacobi-Trudi determinant
      * kostkaNumber -- Compute a Kostka number
      * modificationRule -- Apply the
        Sam-Snowden-Weyman modification rule
      * plethysm -- Plethystic operations on representations
      * scalarProduct -- Standard pairing on symmetric
        functions/class functions
      * schurLevel -- Number of SchurRings the ring is a
        tensor product of.
      * schurResolution -- Compute an ``approximate''
        equivariant resolution of a module.
      * schurRing -- Make a SchurRing
      * specialize -- Specialize a stable character to a
        finite rank
      * symmetricFunction -- Converts class function
        to symmetric function
      * symmetricRing -- Make a Symmetric ring
      * toE -- Elementary symmetric (e-) basis representation
      * toGL -- Express an element in the plain GL Schur basis
      * toH -- Complete symmetric (h-) basis representation
      * toM -- Monomial (m-) basis representation
      * toO -- Expansion in the basis of orthogonal characters
      * toP -- Power-sum (p-) basis representation
      * toRatGL -- Lift a Schur (GL, SL) character into a
        rational-GL Schur ring
      * toS -- Schur (s-) basis representation
      * toSn -- Promote a Schur-basis element into an Sn character
        ring
      * toSp -- Expansion in the basis of symplectic characters
      * toSymm -- Convert a Schur ring element to an element of
        the associated symmetric ring
  * Methods
      * "branch(RingElement,SchurRing,SchurRing)" -- see branch,
        -- Restrict a Schur, Sp, or O character along a two-factor subgroup
      * "branch(RingElement,ZZ,ZZ)" -- see branch, -- Restrict a
        Schur, Sp, or O character along a two-factor subgroup
      * "centralizerSize(List)" -- see centralizerSize,
        -- Size of the centralizer of a permutation
      * "ClassFunction * ClassFunction" -- see ClassFunction,
        -- The class of all Class functions
      * "ClassFunction * Number" -- see ClassFunction, --
        The class of all Class functions
      * "ClassFunction * RingElement" -- see ClassFunction,
        -- The class of all Class functions
      * "ClassFunction + ClassFunction" -- see ClassFunction,
        -- The class of all Class functions
      * "ClassFunction - ClassFunction" -- see ClassFunction,
        -- The class of all Class functions
      * "ClassFunction == ClassFunction" -- see ClassFunction,
        -- The class of all Class functions
      * "Number * ClassFunction" -- see ClassFunction, --
        The class of all Class functions
      * "RingElement * ClassFunction" -- see ClassFunction,
        -- The class of all Class functions
      * "classFunction(RingElement)" -- see classFunction,
        -- Converts symmetric function to class function
      * classFunction(BasicList), --
        Character of irreducible representation of symmetric group
      * coefficientRing(SchurRing), --
        Coefficient ring of a Schur ring
      * "convert(RingElement,Ring)" -- see convert, -- Universal
        dispatcher for converting between Schur ring flavors
      * convert(Number,Ring) (missing documentation)
      * degree(ClassFunction) -- Degree of
        virtual character
      * dim(List,SchurRingElement), --
        dimension of representation
      * "dim(SchurRingElement)" -- see dim(List,SchurRingElement),
        -- dimension of representation
      * "dim(Thing,SchurRingElement)" -- see dim(List,SchurRingElement),
        -- dimension of representation
      * internalProduct(ClassFunction,ClassFunction)
        -- Tensor product
        of virtual representations
      * internalProduct(RingElement,RingElement)
        -- Kronecker product of
        symmetric functions
      * "jacobiTrudi(BasicList,Ring)" -- see jacobiTrudi, --
        Jacobi-Trudi determinant
      * "kostkaNumber(BasicList,BasicList)" -- see kostkaNumber,
        -- Compute a Kostka number
      * numgens(SchurRing) -- Number of
        generators of Schur ring.
      * partitions(Set,BasicList), --
        Partitions of a set
      * "plethysm(RingElement,RingElement)" -- see plethysm, --
        Plethystic operations on representations
      * plethysm(BasicList,RingElement)
        -- Plethystic operations on
        representations
      * "plethysm(BasicList,ClassFunction)" -- see
        plethysm(RingElement,ClassFunction),
        -- Plethystic operations on
        class functions
      * plethysm(RingElement,ClassFunction)
        -- Plethystic operations on
        class functions
      * scalarProduct(ClassFunction,ClassFunction)
        -- Standard scalar
        product of class functions
      * scalarProduct(RingElement,RingElement)
        -- Standard scalar
        product of symmetric functions
      * "schurLevel(Ring)" -- see schurLevel, -- Number of
        SchurRings the ring is a tensor product of.
      * "schurResolution(RingElement,List)" -- see schurResolution,
        -- Compute an ``approximate'' equivariant resolution
        of a module.
      * "schurResolution(RingElement,List,List)" -- see schurResolution,
        -- Compute an ``approximate'' equivariant resolution
        of a module.
      * "SchurRing _ List" -- see SchurRing, -- The class of
        all Schur rings
      * "SchurRing _ Sequence" -- see SchurRing, -- The class
        of all Schur rings
      * "SchurRing _ ZZ" -- see SchurRing, -- The class of all
        Schur rings
      * "schurRing(Ring,Symbol)" -- see schurRing, -- Make a
        SchurRing
      * "schurRing(Ring,Symbol,ZZ)" -- see schurRing, -- Make
        a SchurRing
      * "schurRing(Ring,Thing)" -- see schurRing, -- Make a
        SchurRing
      * "schurRing(Ring,Thing,ZZ)" -- see schurRing, -- Make a
        SchurRing
      * "schurRing(Thing)" -- see schurRing, -- Make a
        SchurRing
      * "schurRing(Thing,ZZ)" -- see schurRing, -- Make a
        SchurRing
      * schurRing(Ring) -- The Schur ring
        corresponding to a given Symmetric ring.
      * "SchurRingIndexedVariableTable _ Thing" -- see
        SchurRingIndexedVariableTable,
      * "specialize(RingElement,List)" -- see specialize, --
        Specialize a stable character to a finite rank
      * "specialize(RingElement,ZZ)" -- see specialize, --
        Specialize a stable character to a finite rank
      * specialize(RingElement,ZZ,SchurRing) (missing documentation)
      * "symmetricFunction(ClassFunction,Ring)" -- see symmetricFunction,
        -- Converts class function to symmetric function
      * "symmetricRing(Ring,ZZ)" -- see symmetricRing, --
        Make a Symmetric ring
      * "symmetricRing(ZZ)" -- see symmetricRing, -- Make
        a Symmetric ring
      * symmetricRing(Ring) -- The Symmetric
        ring corresponding to a given (Schur) ring.
      * "toE(RingElement)" -- see toE, -- Elementary symmetric (e-)
        basis representation
      * "toGL(RingElement)" -- see toGL, -- Express an element in
        the plain GL Schur basis
      * "toGL(RingElement,SchurRing)" -- see toGL, -- Express an
        element in the plain GL Schur basis
      * "toH(RingElement)" -- see toH, -- Complete symmetric (h-)
        basis representation
      * "toM(RingElement)" -- see toM, -- Monomial (m-) basis
        representation
      * "toM(RingElement,SchurRing)" -- see toM, -- Monomial (m-)
        basis representation
      * "toO(RingElement)" -- see toO, -- Expansion in the basis of
        orthogonal characters
      * "toO(RingElement,SchurRing)" -- see toO, -- Expansion in the
        basis of orthogonal characters
      * "toP(RingElement)" -- see toP, -- Power-sum (p-) basis
        representation
      * "toRatGL(RingElement,SchurRing)" -- see toRatGL, -- Lift
        a Schur (GL, SL) character into a rational-GL Schur ring
      * toRatGL(RingElement) (missing documentation)
      * "toS(RingElement)" -- see toS, -- Schur (s-) basis
        representation
      * "toS(RingElement,SchurRing)" -- see toS, -- Schur (s-) basis
        representation
      * "toSn(RingElement,SchurRing)" -- see toSn, -- Promote a
        Schur-basis element into an Sn character ring
      * "toSp(RingElement)" -- see toSp, -- Expansion in the basis
        of symplectic characters
      * "toSp(RingElement,SchurRing)" -- see toSp, -- Expansion in
        the basis of symplectic characters
      * "toSymm(Number)" -- see toSymm, -- Convert a Schur ring
        element to an element of the associated symmetric ring
      * "toSymm(RingElement)" -- see toSymm, -- Convert a Schur
        ring element to an element of the associated symmetric ring
  * Symbols
      * Basis -- Specifies the basis to use for a Schur ring
      * EHPVariables -- Specifies sequence of symbols
        representing e-, h-, and p-functions
      * EorH -- e- or h- representation of Jacobi-Trudi
        determinant
      * eVariable -- Elementary symmetric functions in a
        Symmetric ring
      * GroupActing -- Specifies the group that is acting
      * hVariable -- Complete symmetric functions in a
        Symmetric ring
      * Memoize -- Option to record values of the jacobiTrudi
        function
      * OddOrEven -- Select type $B_n$ or type $D_n$ for an
        orthogonal Schur ring
      * pVariable -- Power-sum symmetric functions in a
        Symmetric ring
      * SVariable -- Specifies symbol representing
        s-functions

For the programmer
==================

The object SchurRings, is a package (Macaulay2Doc),
defined in SchurRings.m2.

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:4922:0.

Basis -- Specifies the basis to use for a Schur ring
****************************************************

Description
===========

This is an optional argument for the schurRing, and
symmetricRing, functions. It selects how the partition-indexed
generators of the ring are interpreted as symmetric functions. The possible
values are "Schur" (the default) and "Monomial".

When Basis => "Schur", the ring generator s_\lambda represents the Schur
function indexed by \lambda. Multiplication uses the Littlewood-Richardson rule
supplied by the Macaulay2 engine.

+---------------------------+
|i1 : S = schurRing(QQ,s,4);|
+---------------------------+
|i2 : s_{2,1} * s_{1}       |
|                           |
|o2 = s    + s    + s       |
|      3,1    2,2    2,1,1  |
|                           |
|o2 : S                     |
+---------------------------+

When Basis => "Monomial", the ring generator m_\lambda instead represents the
monomial symmetric function indexed by \lambda. Multiplication is implemented
by converting to the Schur basis, multiplying there via Littlewood-Richardson,
and converting back to the monomial basis using Kostka numbers. The resulting
ring is abstractly isomorphic to the Schur-basis ring but its elements are
displayed and stored as linear combinations of monomial symmetric functions.

+-----------------------------------------------+
|i3 : M = schurRing(QQ,m,4,Basis => "Monomial");|
+-----------------------------------------------+
|i4 : m_{1} * m_{1}                             |
|                                               |
|o4 = m  + 2m                                   |
|      2     1,1                                |
|                                               |
|o4 : M                                         |
+-----------------------------------------------+
|i5 : m_{2,1} * m_{1}                           |
|                                               |
|o5 = m    + 2m    + 2m                         |
|      3,1     2,2     2,1,1                    |
|                                               |
|o5 : M                                         |
+-----------------------------------------------+

The consistency of the two bases can be verified against toM, which
converts a symmetric function to the monomial basis:

+-----------------------------------------------+
|i6 : S = schurRing(QQ,s,4);                    |
+-----------------------------------------------+
|i7 : M = schurRing(QQ,m,4,Basis => "Monomial");|
+-----------------------------------------------+
|i8 : toM(s_{1} * s_{1},M) == m_{1} * m_{1}     |
|                                               |
|o8 = true                                      |
+-----------------------------------------------+

A monomial-basis product agrees with the Schur-basis product after
round-tripping through toS, verifying that the two rings are isomorphic with
isomorphism toM/toS:

+----------------------------------------+
|i9 : x = s_{2,1} * s_{1};               |
+----------------------------------------+
|i10 : y = toM(x,M);                     |
+----------------------------------------+
|i11 : y                                 |
|                                        |
|o11 = m    + 2m    + 4m      + 8m       |
|       3,1     2,2     2,1,1     1,1,1,1|
|                                        |
|o11 : M                                 |
+----------------------------------------+
|i12 : toS(y,S) == x                     |
|                                        |
|o12 = true                              |
+----------------------------------------+

Converting back from the monomial basis to the Schur basis recovers the
original Schur element:

+---------------------------------+
|i13 : toS(m_{2,1} + m_{1,1,1}, S)|
|                                 |
|o13 = s    - s                   |
|       2,1    1,1,1              |
|                                 |
|o13 : S                          |
+---------------------------------+

The monomial-to-Schur transition is essentially indexed by kostkaNumber,:
the coefficient of m_\mu in s_\lambda equals K_{\lambda,\mu}.
For example, the Kostka numbers with \lambda = (2,1) reproduce the monomial
expansion of s_{(2,1)}:

+---------------------------------+
|i14 : toM s_{2,1}                |
|                                 |
|o14 = m    + 2m                  |
|       2,1     1,1,1             |
|                                 |
|o14 : schurRing (QQ, m, 4)       |
+---------------------------------+
|i15 : kostkaNumber({2,1},{2,1})  |
|                                 |
|o15 = 1                          |
+---------------------------------+
|i16 : kostkaNumber({2,1},{1,1,1})|
|                                 |
|o16 = 2                          |
+---------------------------------+

See also
========

  * schurRing -- Make a SchurRing
  * symmetricRing -- Make a Symmetric ring
  * toM -- Monomial (m-) basis representation
  * kostkaNumber -- Compute a Kostka number
  * GroupActing -- Specifies the group that is acting

Functions with optional argument named Basis:
=============================================

  * "schurRing(...,Basis=>...)"
  * "symmetricRing(...,Basis=>...)"

For the programmer
==================

The object Basis, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8010:0.

branch -- Restrict a Schur, Sp, or O character along a two-factor subgroup
**************************************************************************

  * Usage:
        h = branch(f, S1, S2)
        h = branch(f, m, n)
  * Inputs:
      * f, a ring element (Macaulay2Doc), an element of a
        SchurRing of type GL, Sp, or O (stable or finite rank)
      * S1, a Schur ring, the first factor ring (same
        GroupActing as the ring of f)
      * S2, a Schur ring, the second factor ring (same
        GroupActing as the ring of f)
      * m, an integer (Macaulay2Doc), the rank of the first factor
        (alternate interface)
      * n, an integer (Macaulay2Doc), the rank of the second factor
  * Outputs:
      * h, a hash table (Macaulay2Doc), mapping pairs of
        partitions (mu, nu) to coefficients.  The entry h#(mu,nu) is the
        multiplicity of the irreducible indexed by the pair in the branching of
        f.

Description
===========

Implements the classical branching rules of R.\ C.\ King, Branching rules for
classical Lie groups using tensor and spinor methods, J.\ Phys.\ A 8 (1975),
429–449.  For any partition $\lambda$ and a two-factor restriction of the
classical group, the character decomposes by a universal formula expressed via
the triple Littlewood–Richardson coefficient $c^\lambda_{\alpha,\beta,\gamma}$
(the coefficient of $s_\lambda$ in $s_\alpha s_\beta s_\gamma$).

$\bullet$ GL:  $s_\lambda \mid_{GL(m)\times GL(n)} = \sum c^\lambda_{\mu,\nu}\,
s_\mu \otimes s_\nu$ (the coproduct of Schur functions).

$\bullet$ Sp:  $sp_\lambda \mid_{Sp(2m)\times Sp(2n)} = \sum_{\delta\text{
cols-even}} c^\lambda_{\delta,\mu,\nu}\, sp_\mu \otimes sp_\nu$, the sum
running over partitions $\delta$ whose conjugate has all parts even
(equivalently, the parts of $\delta$ appear with even multiplicity).

$\bullet$ O:  $o_\lambda \mid_{O(a)\times O(b)} = \sum_{\delta\text{
rows-even}} c^\lambda_{\delta,\mu,\nu}\, o_\mu \otimes o_\nu$, where $\delta$
ranges over partitions with all parts even.

For finite-rank factors the output partitions are collapsed via the
Sam–Snowden–Weyman modification rules, so any $(\mu,\nu)$ that is killed or
re-signed by the rule is handled automatically.

+-----------------------------------------------------------------------------+
|i1 : S = schurRing(QQ, s, infinity);                                         |
+-----------------------------------------------------------------------------+
|i2 : A = schurRing(QQ, a, infinity);                                         |
+-----------------------------------------------------------------------------+
|i3 : B = schurRing(QQ, b, infinity);                                         |
+-----------------------------------------------------------------------------+
|i4 : pairs branch(S_{2,1}, A, B)                                             |
|                                                                             |
|o4 = {(({1}, {1, 1}), 1), (({1}, {2}), 1), (({2}, {1}), 1), (({1, 1}, {1}),  |
|     ------------------------------------------------------------------------|
|     1), (({2, 1}, {}), 1), (({}, {2, 1}), 1)}                               |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

A slightly larger GL example: the restriction of $s_{3,2}$ along $GL(\cdot)
\times GL(\cdot)$ produces the full coproduct of the Schur function, one term
per ordered pair $(\mu,\nu)$ with $c^{(3,2)}_{\mu,\nu}$ nonzero:

+-----------------------------------------------------------------------------+
|i5 : pairs branch(S_{3,2}, A, B)                                             |
|                                                                             |
|o5 = {(({2, 1}, {1, 1}), 1), (({3, 1}, {1}), 1), (({1, 1}, {2, 1}), 1), (({},|
|     ------------------------------------------------------------------------|
|     {3, 2}), 1), (({1}, {3, 1}), 1), (({3, 2}, {}), 1), (({2}, {2, 1}), 1), |
|     ------------------------------------------------------------------------|
|     (({2}, {3}), 1), (({2, 2}, {1}), 1), (({2, 1}, {2}), 1), (({3}, {2}),   |
|     ------------------------------------------------------------------------|
|     1), (({1}, {2, 2}), 1)}                                                 |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

The Sp branching picks up an extra (mu, nu) = ({}, {}) term for $sp_{1,1}$ via
$\delta = (1,1)$:

+---------------------------------------------------------------------------+
|i6 : Sp  = schurRing(QQ, sp,  infinity, GroupActing => "Sp");              |
+---------------------------------------------------------------------------+
|i7 : Asp = schurRing(QQ, asp, infinity, GroupActing => "Sp");              |
+---------------------------------------------------------------------------+
|i8 : Bsp = schurRing(QQ, bsp, infinity, GroupActing => "Sp");              |
+---------------------------------------------------------------------------+
|i9 : pairs branch(Sp_{1,1}, Asp, Bsp)                                      |
|                                                                           |
|o9 = {(({}, {}), 1), (({1, 1}, {}), 1), (({}, {1, 1}), 1), (({1}, {1}), 1)}|
|                                                                           |
|o9 : List                                                                  |
+---------------------------------------------------------------------------+

For $sp_{2,1}$ the Sp branching sum runs over the two columns-even deltas
$\delta = ()$ and $\delta = (1,1)$; the latter gives the correction terms
supported on partitions of total weight one:

+-----------------------------------------------------------------------------+
|i10 : pairs branch(Sp_{2,1}, Asp, Bsp)                                       |
|                                                                             |
|o10 = {(({1, 1}, {1}), 1), (({1}, {1, 1}), 1), (({1}, {}), 1), (({}, {1}),   |
|      -----------------------------------------------------------------------|
|      1), (({2, 1}, {}), 1), (({2}, {1}), 1), (({}, {2, 1}), 1), (({1}, {2}),|
|      -----------------------------------------------------------------------|
|      1)}                                                                    |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+

On the orthogonal side, the branching of $o_{2,1}$ runs over rows-even deltas
$\delta = ()$ and $\delta = (2)$, contributing correction terms of total weight
one:

+-----------------------------------------------------------------------------+
|i11 : O  = schurRing(QQ, oGp, infinity, GroupActing => "O");                 |
+-----------------------------------------------------------------------------+
|i12 : AO = schurRing(QQ, aO,  infinity, GroupActing => "O");                 |
+-----------------------------------------------------------------------------+
|i13 : BO = schurRing(QQ, bO,  infinity, GroupActing => "O");                 |
+-----------------------------------------------------------------------------+
|i14 : pairs branch(oGp_{2,1}, AO, BO)                                        |
|                                                                             |
|o14 = {(({1, 1}, {1}), 1), (({1}, {1, 1}), 1), (({1}, {}), 1), (({}, {1}),   |
|      -----------------------------------------------------------------------|
|      1), (({2, 1}, {}), 1), (({2}, {1}), 1), (({}, {2, 1}), 1), (({1}, {2}),|
|      -----------------------------------------------------------------------|
|      1)}                                                                    |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+

The ZZ, ZZ form is a convenience that builds anonymous factor rings of the
requested ranks (with the same GroupActing and, for O, the same OddOrEven).

+------------------------------------------------------------------------+
|i15 : Sp4 = schurRing(QQ, sp4, 2, GroupActing => "Sp");                 |
+------------------------------------------------------------------------+
|i16 : pairs branch(Sp4_{2,1}, 1, 1)                                     |
|                                                                        |
|o16 = {(({1}, {}), 1), (({}, {1}), 1), (({2}, {1}), 1), (({1}, {2}), 1)}|
|                                                                        |
|o16 : List                                                              |
+------------------------------------------------------------------------+

The (m,n) shortcut agrees with the result of spelling out anonymous factor
rings.  For the GL branching of $s_{3,2}$ along $GL(2)\times GL(2)$:

+-----------------------------------------------------------------------------+
|i17 : pairs branch(S_{3,2}, 2, 2)                                            |
|                                                                             |
|o17 = {(({2, 1}, {1, 1}), 1), (({3, 1}, {1}), 1), (({1, 1}, {2, 1}), 1),     |
|      -----------------------------------------------------------------------|
|      (({}, {3, 2}), 1), (({1}, {3, 1}), 1), (({3, 2}, {}), 1), (({2}, {2,   |
|      -----------------------------------------------------------------------|
|      1}), 1), (({2}, {3}), 1), (({2, 2}, {1}), 1), (({2, 1}, {2}), 1),      |
|      -----------------------------------------------------------------------|
|      (({3}, {2}), 1), (({1}, {2, 2}), 1)}                                   |
|                                                                             |
|o17 : List                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * schurRing -- Make a SchurRing
  * specialize -- Specialize a stable character to a finite
    rank
  * GroupActing -- Specifies the group that is acting
  * modificationRule -- Apply the Sam-Snowden-Weyman
    modification rule

Ways to use branch:
===================

  * "branch(RingElement,SchurRing,SchurRing)"
  * "branch(RingElement,ZZ,ZZ)"

For the programmer
==================

The object branch, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8542:0.

centralizerSize -- Size of the centralizer of a permutation
***********************************************************

  * Usage:
        n = centralizerSize(rho)
  * Inputs:
      * rho, a list (Macaulay2Doc),
  * Outputs:
      * n, an integer (Macaulay2Doc),

Description
===========

rho is a list representing the cycle type of some permutation: the i-th entry
in rho is the number of cycles of length i of the permutation. The output of
the function centralizerSize is the size of the centralizer in the symmetric
group of any permutation of cycle type rho.  If the cycle type rho corresponds
to a partition \lambda, then centralizerSize(rho) is also the value of the
square norm <p_\lambda, p_\lambda>.

+-----------------------------+
|i1 : centralizerSize{1,1,1}  |
|                             |
|o1 = 6                       |
+-----------------------------+
|i2 : R = symmetricRing(QQ,6);|
+-----------------------------+
|i3 : u = p_1 * p_2 * p_3;    |
+-----------------------------+
|i4 : scalarProduct(u,u)      |
|                             |
|o4 = 6                       |
|                             |
|o4 : QQ                      |
+-----------------------------+

A few values of z_\rho for small cycle types: the identity of S_n has
centralizer size n!, while an n-cycle has centralizer of size n (generated by
itself).

+---------------------------------------------------------------------+
|i5 : centralizerSize{4}           -- cycle type (1,1,1,1), all of S_4|
|                                                                     |
|o5 = 24                                                              |
+---------------------------------------------------------------------+
|i6 : centralizerSize{0,0,0,1}     -- a single 4-cycle                |
|                                                                     |
|o6 = 4                                                               |
+---------------------------------------------------------------------+
|i7 : centralizerSize{2,1}         -- cycle type (2,1,1)              |
|                                                                     |
|o7 = 4                                                               |
+---------------------------------------------------------------------+

Burnside's classical identity \sum_{\lambda \vdash n} 1/z_\lambda = 1 expresses
that the uniform measure on S_n sums to 1. We verify this for n = 5:

+-----------------------------------------------------------------------------+
|i8 : parts5 = {{5}, {4,1}, {3,2}, {3,1,1}, {2,2,1}, {2,1,1,1}, {1,1,1,1,1}}; |
+-----------------------------------------------------------------------------+
|i9 : cycMult = la -> apply(toList(1..max la), i -> #positions(la, j -> j ==  |
|-----------------------------------------------------------------------------|
|i));                                                                         |
+-----------------------------------------------------------------------------+
|i10 : sum(parts5, la -> 1/centralizerSize cycMult la)                        |
|                                                                             |
|o10 = 1                                                                      |
|                                                                             |
|o10 : QQ                                                                     |
+-----------------------------------------------------------------------------+

See also
========

  * scalarProduct -- Standard pairing on symmetric
    functions/class functions

Ways to use centralizerSize:
============================

  * "centralizerSize(List)"

For the programmer
==================

The object centralizerSize, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7665:0.

ClassFunction -- The class of all Class functions
*************************************************

Description
===========

A class function (or virtual character of a symmetric group S_n) is a function
that is constant on the conjugacy classes of S_n. Class functions for S_n are
in one-to-one correspondence with symmetric functions of degree n.  The class
functions corresponding to actual representations of S_n are called characters.

The character of the standard representation of S_3 is

+----------------------------------+
|i1 : S = schurRing(QQ,s,3);       |
+----------------------------------+
|i2 : classFunction(s_{2,1})       |
|                                  |
|o2 = ClassFunction{{1, 1, 1} => 2}|
|                   {3} => -1      |
|                                  |
|o2 : ClassFunction                |
+----------------------------------+

The character of the sign representation of S_5 is

+----------------------------------------+
|i3 : S = schurRing(QQ,s,5);             |
+----------------------------------------+
|i4 : classFunction(s_{1,1,1,1,1})       |
|                                        |
|o4 = ClassFunction{{1, 1, 1, 1, 1} => 1}|
|                   {2, 1, 1, 1} => -1   |
|                   {2, 2, 1} => 1       |
|                   {3, 1, 1} => 1       |
|                   {3, 2} => -1         |
|                   {4, 1} => -1         |
|                   {5} => 1             |
|                                        |
|o4 : ClassFunction                      |
+----------------------------------------+

We can go back and forth between class functions and symmetric functions.

+-----------------------------------------------------------+
|i5 : R = symmetricRing(QQ,3);                              |
+-----------------------------------------------------------+
|i6 : cF = new ClassFunction from {{1,1,1} => 2, {3} => -1};|
+-----------------------------------------------------------+
|i7 : sF = symmetricFunction(cF,R)                          |
|                                                           |
|     1 3   1                                               |
|o7 = -p  - -p                                              |
|     3 1   3 3                                             |
|                                                           |
|o7 : R                                                     |
+-----------------------------------------------------------+
|i8 : toS sF                                                |
|                                                           |
|o8 = s                                                     |
|      2,1                                                  |
|                                                           |
|o8 : schurRing (QQ, s, 3)                                  |
+-----------------------------------------------------------+
|i9 : classFunction sF                                      |
|                                                           |
|o9 = ClassFunction{{1, 1, 1} => 2}                         |
|                   {3} => -1                               |
|                                                           |
|o9 : ClassFunction                                         |
+-----------------------------------------------------------+

We can add, subtract, multiply, scale class functions:

+------------------------------------------+
|i10 : S = schurRing(QQ,s,4);              |
+------------------------------------------+
|i11 : c1 = classFunction(S_{2,1,1}-S_{4});|
+------------------------------------------+
|i12 : c2 = classFunction(S_{3,1});        |
+------------------------------------------+
|i13 : c1 + c2                             |
|                                          |
|o13 = ClassFunction{{1, 1, 1, 1} => 5}    |
|                    {2, 1, 1} => -1       |
|                    {2, 2} => -3          |
|                    {3, 1} => -1          |
|                    {4} => -1             |
|                                          |
|o13 : ClassFunction                       |
+------------------------------------------+
|i14 : c1 * c2                             |
|                                          |
|o14 = ClassFunction{{1, 1, 1, 1} => 6}    |
|                    {2, 1, 1} => -2       |
|                    {2, 2} => 2           |
|                                          |
|o14 : ClassFunction                       |
+------------------------------------------+
|i15 : 3*c1 - c2*2                         |
|                                          |
|o15 = ClassFunction{{2, 1, 1} => -8}      |
|                    {2, 2} => -4          |
|                    {3, 1} => -3          |
|                    {4} => 2              |
|                                          |
|o15 : ClassFunction                       |
+------------------------------------------+

The trivial and sign representations of S_4 are the characters of the shapes
(4) and (1,1,1,1).  Their pointwise product (which is c_1 * c_2 on
ClassFunction) gives the sign representation back:

+--------------------------------------+
|i16 : T = schurRing(QQ,t,4);          |
+--------------------------------------+
|i17 : triv = classFunction(t_{4})     |
|                                      |
|o17 = ClassFunction{{1, 1, 1, 1} => 1}|
|                    {2, 1, 1} => 1    |
|                    {2, 2} => 1       |
|                    {3, 1} => 1       |
|                    {4} => 1          |
|                                      |
|o17 : ClassFunction                   |
+--------------------------------------+
|i18 : sgn = classFunction(t_{1,1,1,1})|
|                                      |
|o18 = ClassFunction{{1, 1, 1, 1} => 1}|
|                    {2, 1, 1} => -1   |
|                    {2, 2} => 1       |
|                    {3, 1} => 1       |
|                    {4} => -1         |
|                                      |
|o18 : ClassFunction                   |
+--------------------------------------+
|i19 : triv * sgn == sgn               |
|                                      |
|o19 = true                            |
+--------------------------------------+

The regular representation of S_n has character n! on the identity class (1^n)
and 0 elsewhere.  By Frobenius reciprocity, it pairs trivially with the trivial
character:

+----------------------------------------------------+
|i20 : reg = new ClassFunction from {{1,1,1,1} => 24}|
|                                                    |
|o20 = ClassFunction{{1, 1, 1, 1} => 24}             |
|                                                    |
|o20 : ClassFunction                                 |
+----------------------------------------------------+
|i21 : scalarProduct(reg, triv)                      |
|                                                    |
|o21 = 1                                             |
|                                                    |
|o21 : QQ                                            |
+----------------------------------------------------+

Products of class functions of induced/restricted representations recover
well-known decompositions: the tensor square of the standard representation of
S_4 pairs nontrivially with both the trivial and sign characters:

+-----------------------------------+
|i22 : std = classFunction(t_{3,1});|
+-----------------------------------+
|i23 : sq = std * std;              |
+-----------------------------------+
|i24 : scalarProduct(sq, triv)      |
|                                   |
|o24 = 1                            |
|                                   |
|o24 : QQ                           |
+-----------------------------------+
|i25 : scalarProduct(sq, sgn)       |
|                                   |
|o25 = 0                            |
|                                   |
|o25 : QQ                           |
+-----------------------------------+

Methods that use a Class function:
==================================

  * "ClassFunction * ClassFunction"
  * "ClassFunction * Number"
  * "ClassFunction * RingElement"
  * "ClassFunction + ClassFunction"
  * "ClassFunction - ClassFunction"
  * "ClassFunction == ClassFunction"
  * "Number * ClassFunction"
  * "RingElement * ClassFunction"
  * degree(ClassFunction) -- Degree of
    virtual character
  * internalProduct(ClassFunction,ClassFunction)
    -- Tensor product of
    virtual representations
  * "plethysm(BasicList,ClassFunction)" -- see
    plethysm(RingElement,ClassFunction),
    -- Plethystic operations on
    class functions
  * plethysm(RingElement,ClassFunction)
    -- Plethystic operations on
    class functions
  * scalarProduct(ClassFunction,ClassFunction)
    -- Standard scalar
    product of class functions
  * "symmetricFunction(ClassFunction,Ring)" -- see symmetricFunction,
    -- Converts class function to symmetric function

For the programmer
==================

The object ClassFunction, is a type (Macaulay2Doc),
with ancestor classes HashTable (Macaulay2Doc),
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7050:0.

classFunction -- Converts symmetric function to class function
**************************************************************

  * Usage:
        ch = classFunction(f)
  * Inputs:
      * f, a ring element (Macaulay2Doc), element of a
        Symmetric ring
  * Outputs:
      * ch, a Class function,

Description
===========

Given a symmetric function f, homogeneous of degree N, the method computes the
corresponding virtual character of the symmetric group S_N.

The character of the standard representation of S_5 is

+----------------------------------------+
|i1 : R = symmetricRing(QQ,5);           |
+----------------------------------------+
|i2 : classFunction(jacobiTrudi({4,1},R))|
|                                        |
|o2 = ClassFunction{{1, 1, 1, 1, 1} => 4}|
|                   {2, 1, 1, 1} => 2    |
|                   {3, 1, 1} => 1       |
|                   {3, 2} => -1         |
|                   {5} => -1            |
|                                        |
|o2 : ClassFunction                      |
+----------------------------------------+

The character of the second exterior power of the standard representation of
S_5 is

+------------------------------------------+
|i3 : R = symmetricRing(QQ,5);             |
+------------------------------------------+
|i4 : classFunction(jacobiTrudi({3,1,1},R))|
|                                          |
|o4 = ClassFunction{{1, 1, 1, 1, 1} => 6}  |
|                   {2, 2, 1} => -2        |
|                   {5} => 1               |
|                                          |
|o4 : ClassFunction                        |
+------------------------------------------+

The sign representation of S_n corresponds to the Schur polynomial of shape
(1^n).  Its class function takes the value sgn(\sigma) on a permutation of
cycle type \rho

+----------------------------------------+
|i5 : Ssign = schurRing(QQ,s,5);         |
+----------------------------------------+
|i6 : classFunction(s_{1,1,1,1,1})       |
|                                        |
|o6 = ClassFunction{{1, 1, 1, 1, 1} => 1}|
|                   {2, 1, 1, 1} => -1   |
|                   {2, 2, 1} => 1       |
|                   {3, 1, 1} => 1       |
|                   {3, 2} => -1         |
|                   {4, 1} => -1         |
|                   {5} => 1             |
|                                        |
|o6 : ClassFunction                      |
+----------------------------------------+

Small-n character tables are assembled row-by-row from classFunction.  For S_3
there are three conjugacy classes (1^3), (2,1), (3) and three irreducibles, and
the values are collected below:

+-----------------------------------------------------------------------------+
|i7 : R3 = symmetricRing(QQ,3);                                               |
+-----------------------------------------------------------------------------+
|i8 : for lam in {{3},{2,1},{1,1,1}} list classFunction(jacobiTrudi(lam,R3))  |
|                                                                             |
|o8 = {ClassFunction{{1, 1, 1} => 1}, ClassFunction{{1, 1, 1} => 2},          |
|                    {2, 1} => 1                    {3} => -1                 |
|                    {3} => 1                                                 |
|     ------------------------------------------------------------------------|
|     ClassFunction{{1, 1, 1} => 1}}                                          |
|                   {2, 1} => -1                                              |
|                   {3} => 1                                                  |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

Tensor products of S_n-representations correspond to internalProduct of class
functions.  For S_4 the tensor square of the standard representation decomposes
into irreducibles by pairing with each irreducible character via
scalarProduct,:

+-------------------------------------------------------------+
|i9 : R4 = symmetricRing(QQ,4);                               |
+-------------------------------------------------------------+
|i10 : std = classFunction(jacobiTrudi({3,1},R4));            |
+-------------------------------------------------------------+
|i11 : sq = internalProduct(std, std);                        |
+-------------------------------------------------------------+
|i12 : for lam in {{4},{3,1},{2,2},{2,1,1},{1,1,1,1}} list    |
|        scalarProduct(sq, classFunction(jacobiTrudi(lam,R4)))|
|                                                             |
|o12 = {1, 1, 1, 1, 0}                                        |
|                                                             |
|o12 : List                                                   |
+-------------------------------------------------------------+

See also
========

  * symmetricFunction -- Converts class function to
    symmetric function

Ways to use classFunction:
==========================

  * "classFunction(RingElement)"
  * classFunction(BasicList) -- Character
    of irreducible representation of symmetric group

For the programmer
==================

The object classFunction, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7221:0.

classFunction(BasicList) -- Character of irreducible representation of symmetric group
**************************************************************************************

  * Function: classFunction,
  * Usage:
        ch = classFunction(l)
  * Inputs:
      * l, a basic list (Macaulay2Doc), partition
  * Outputs:
      * ch, a Class function,

Description
===========

Given a partition l of N, the method computes the character of the irreducible
S_N-representation corresponding to the partition l.

+--------------------------------------------+
|i1 : R = symmetricRing(QQ,7);               |
+--------------------------------------------+
|i2 : cF = classFunction({3,2,1})            |
|                                            |
|o2 = ClassFunction{{1, 1, 1, 1, 1, 1} => 16}|
|                   {3, 1, 1, 1} => -2       |
|                   {3, 3} => -2             |
|                   {5, 1} => 1              |
|                                            |
|o2 : ClassFunction                          |
+--------------------------------------------+
|i3 : toS(symmetricFunction(cF,R))           |
|                                            |
|o3 = s                                      |
|      3,2,1                                 |
|                                            |
|o3 : schurRing (QQ, s, 7)                   |
+--------------------------------------------+

Enumerating the irreducible characters of S_4 and pairing them with
scalarProduct, recovers the orthonormality relations from
representation theory -- the diagonal entries are 1 and the off-diagonal
entries are 0:

+----------------------------------------------------------------------+
|i4 : chars = for lam in partitions 4 list classFunction toList lam;   |
+----------------------------------------------------------------------+
|i5 : matrix for a in chars list for b in chars list scalarProduct(a,b)|
|                                                                      |
|o5 = | 1 0 0 0 0 |                                                    |
|     | 0 1 0 0 0 |                                                    |
|     | 0 0 1 0 0 |                                                    |
|     | 0 0 0 1 0 |                                                    |
|     | 0 0 0 0 1 |                                                    |
|                                                                      |
|              5       5                                               |
|o5 : Matrix QQ  <-- QQ                                                |
+----------------------------------------------------------------------+

Irreducible characters of different shapes are orthogonal.  Here we verify
orthogonality for three partitions of 6:

+---------------------------------+
|i6 : c1 = classFunction({3,2,1});|
+---------------------------------+
|i7 : c2 = classFunction({4,1,1});|
+---------------------------------+
|i8 : c3 = classFunction({2,2,2});|
+---------------------------------+
|i9 : scalarProduct(c1,c2)        |
|                                 |
|o9 = 0                           |
|                                 |
|o9 : QQ                          |
+---------------------------------+
|i10 : scalarProduct(c2,c3)       |
|                                 |
|o10 = 0                          |
|                                 |
|o10 : QQ                         |
+---------------------------------+

Self-pairings return 1 for each irreducible, independent of the shape, and the
trivial (row shape) and sign (column shape) characters are the 1-dimensional
irreducibles:

+-----------------------------------------+
|i11 : scalarProduct(c1,c1)               |
|                                         |
|o11 = 1                                  |
|                                         |
|o11 : QQ                                 |
+-----------------------------------------+
|i12 : classFunction({5})                 |
|                                         |
|o12 = ClassFunction{{1, 1, 1, 1, 1} => 1}|
|                    {2, 1, 1, 1} => 1    |
|                    {2, 2, 1} => 1       |
|                    {3, 1, 1} => 1       |
|                    {3, 2} => 1          |
|                    {4, 1} => 1          |
|                    {5} => 1             |
|                                         |
|o12 : ClassFunction                      |
+-----------------------------------------+
|i13 : classFunction({1,1,1,1,1})         |
|                                         |
|o13 = ClassFunction{{1, 1, 1, 1, 1} => 1}|
|                    {2, 1, 1, 1} => -1   |
|                    {2, 2, 1} => 1       |
|                    {3, 1, 1} => 1       |
|                    {3, 2} => -1         |
|                    {4, 1} => -1         |
|                    {5} => 1             |
|                                         |
|o13 : ClassFunction                      |
+-----------------------------------------+

See also
========

  * symmetricFunction -- Converts class function to
    symmetric function

Ways to use this method:
========================

  * classFunction(BasicList) -- Character
    of irreducible representation of symmetric group
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7279:0.

coefficientRing(SchurRing) -- Coefficient ring of a Schur ring
**************************************************************

  * Function: coefficientRing (Macaulay2Doc),
  * Usage:
        coefficientRing S
  * Inputs:
      * S, a Schur ring,
  * Outputs:
      * a ring (Macaulay2Doc),

Description
===========

Given a Schur ring S, the function returns its coefficient ring. The
coefficient ring may be any commutative ring that Macaulay2 supports, including
other Schur rings obtained by iterating schurRing.

+------------------------------+
|i1 : S = schurRing(ZZ[x],s,4);|
+------------------------------+
|i2 : coefficientRing S        |
|                              |
|o2 = ZZ[x]                    |
|                              |
|o2 : PolynomialRing           |
+------------------------------+
|i3 : A = schurRing(QQ,a,3);   |
+------------------------------+
|i4 : B = schurRing(A,b,2);    |
+------------------------------+
|i5 : coefficientRing B        |
|                              |
|o5 = A                        |
|                              |
|o5 : SchurRing                |
+------------------------------+

For a tower of Schur rings, coefficientRing peels off one layer at a time,
allowing the user to navigate the entire construction.

+--------------------------------------+
|i6 : T = schurRing(B,t,2);            |
+--------------------------------------+
|i7 : coefficientRing T                |
|                                      |
|o7 = B                                |
|                                      |
|o7 : SchurRing                        |
+--------------------------------------+
|i8 : coefficientRing coefficientRing T|
|                                      |
|o8 = A                                |
|                                      |
|o8 : SchurRing                        |
+--------------------------------------+

One can build Schur rings over finite-field coefficients as well.

+-----------------------------------------------------------------------------+
|i9 : P = schurRing(ZZ/5,p,4);                                                |
+-----------------------------------------------------------------------------+
|i10 : coefficientRing P                                                      |
|                                                                             |
|      ZZ                                                                     |
|o10 = --                                                                     |
|       5                                                                     |
|                                                                             |
|o10 : QuotientRing                                                           |
+-----------------------------------------------------------------------------+
|i11 : (p_{2,1} + p_{1})^2                                                    |
|                                                                             |
|o11 = p    + p      + p    + 2p      + p        + 2p    + p      + p        +|
|       4,2    4,1,1    3,3     3,2,1    3,1,1,1     3,1    2,2,2    2,2,1,1  |
|      -----------------------------------------------------------------------|
|      2p    + 2p      + p  + p                                               |
|        2,2     2,1,1    2    1,1                                            |
|                                                                             |
|o11 : P                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * schurRing -- Make a SchurRing
  * SchurRing -- The class of all Schur rings

Ways to use this method:
========================

  * coefficientRing(SchurRing), --
    Coefficient ring of a Schur ring
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5203:0.

convert -- Universal dispatcher for converting between Schur ring flavors
*************************************************************************

  * Usage:
        g = convert(f, T)
  * Inputs:
      * f, a ring element (Macaulay2Doc), any
        symmetric-function-like element
      * T, a ring (Macaulay2Doc), target SchurRing,
        or symmetricRing,
  * Outputs:
      * g, a ring element (Macaulay2Doc), f expressed in the
        natural basis of T

Description
===========

convert is a thin routing layer that inspects the target ring's classification
and dispatches to the appropriate specialized converter:

\begin{itemize} \item SchurRing, with GroupActing => "GL"
$\to$ See toS, \item SchurRing, with GroupActing =>
"Sn"  $\to$ See toSn, \item SchurRing, with
GroupActing => "Sp"  $\to$ See toSp, \item SchurRing,
with GroupActing => "O"   $\to$ See toO, \item SchurRing,
with GroupActing => "SL"  $\to$ See toS, \item
SchurRing, with GroupActing => "RatGL" $\to$ See toRatGL,
\item symmetricRing, $\to$ See toSymm,
followed by promotion. \end{itemize}

No new conversion mathematics is performed here; convert exists purely to
simplify user-level code that does not want to know which specialized converter
to call.

+---------------------------------------------------+
|i1 : S  = schurRing(QQ, s, 4);                     |
+---------------------------------------------------+
|i2 : Sp = schurRing(QQ, p, 2, GroupActing => "Sp");|
+---------------------------------------------------+
|i3 : O  = schurRing(QQ, o, 4, GroupActing => "O"); |
+---------------------------------------------------+
|i4 : Sn = schurRing(QQ, n, 4, GroupActing => "Sn");|
+---------------------------------------------------+
|i5 : convert(s_{2,1}, Sp)                          |
|                                                   |
|o5 = p    + p                                      |
|      2,1    1                                     |
|                                                   |
|o5 : Sp                                            |
+---------------------------------------------------+
|i6 : convert(s_{2,1}, O)                           |
|                                                   |
|o6 = o    + o                                      |
|      2,1    1                                     |
|                                                   |
|o6 : O                                             |
+---------------------------------------------------+
|i7 : convert(s_{2,1}, Sn)                          |
|                                                   |
|o7 = n                                             |
|      2,1                                          |
|                                                   |
|o7 : Sn                                            |
+---------------------------------------------------+

The dispatch works from any source basis to any target basis. Below we start
from a monomial-basis Schur ring and send the same element into each of the
flavors -- the dispatcher selects toS, toSp, toO, and toSn respectively:

+-----------------------------------------------------+
|i8 : M    = schurRing(QQ, m, 4, Basis => "Monomial");|
+-----------------------------------------------------+
|i9 : convert(m_{2,1}, S)                             |
|                                                     |
|o9 = s    - 2s                                       |
|      2,1     1,1,1                                  |
|                                                     |
|o9 : S                                               |
+-----------------------------------------------------+
|i10 : convert(m_{2,1}, Sp)                           |
|                                                     |
|o10 = p    - p                                       |
|       2,1    1                                      |
|                                                     |
|o10 : Sp                                             |
+-----------------------------------------------------+
|i11 : convert(m_{2,1}, O)                            |
|                                                     |
|o11 = o    - 2o      + o                             |
|       2,1     1,1,1    1                            |
|                                                     |
|o11 : O                                              |
+-----------------------------------------------------+
|i12 : convert(m_{2,1}, Sn)                           |
|                                                     |
|o12 = n    - 2n                                      |
|       2,1     1,1,1                                 |
|                                                     |
|o12 : Sn                                             |
+-----------------------------------------------------+

To a rational-GL target, the dispatcher uses toRatGL, which
embeds a plain GL Schur character $s_\lambda$ as the bipartition $s_{(\lambda,
())}$:

+------------------------------------------------------------+
|i13 : RRat = schurRing(QQ, rRat, 4, GroupActing => "RatGL");|
+------------------------------------------------------------+
|i14 : convert(s_{2,1}, RRat)                                |
|                                                            |
|o14 = rRat                                                  |
|          {{2, 1}, {}}                                      |
|                                                            |
|o14 : RRat                                                  |
+------------------------------------------------------------+
|i15 : convert(s_{3} + 2*s_{1,1}, RRat)                      |
|                                                            |
|o15 = rRat          + 2rRat                                 |
|          {{3}, {}}        {{1, 1}, {}}                     |
|                                                            |
|o15 : RRat                                                  |
+------------------------------------------------------------+

A symmetricRing source is also handled: here the dispatcher routes through
toSymm and lands in the Schur basis of the target ring.

+-------------------------------+
|i16 : U = symmetricRing(QQ, 4);|
+-------------------------------+
|i17 : convert(e_1 * h_2, S)    |
|                               |
|o17 = s  + s                   |
|       3    2,1                |
|                               |
|o17 : S                        |
+-------------------------------+
|i18 : convert(p_3, S)          |
|                               |
|o18 = s                        |
|       3                       |
|                               |
|o18 : S                        |
+-------------------------------+

See also
========

  * toS -- Schur (s-) basis representation
  * toSn -- Promote a Schur-basis element into an Sn character
    ring
  * toGL -- Express an element in the plain GL Schur basis
  * toSp -- Expansion in the basis of symplectic characters
  * toO -- Expansion in the basis of orthogonal characters
  * toRatGL -- Lift a Schur (GL, SL) character into a
    rational-GL Schur ring
  * toSymm -- Convert a Schur ring element to an element of the
    associated symmetric ring

Ways to use convert:
====================

  * "convert(RingElement,Ring)"
  * convert(Number,Ring) (missing documentation)

For the programmer
==================

The object convert, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8981:0.

degree(ClassFunction) -- Degree of virtual character
****************************************************

  * Function: degree (Macaulay2Doc),

Description
===========

For a virtual character ch of a symmetric group on n letters, the degree of ch
is n.

+----------------------------------------+
|i1 : S = schurRing(s,5);                |
+----------------------------------------+
|i2 : ch = classFunction s_(3,1,1)       |
|                                        |
|o2 = ClassFunction{{1, 1, 1, 1, 1} => 6}|
|                   {2, 2, 1} => -2      |
|                   {5} => 1             |
|                                        |
|o2 : ClassFunction                      |
+----------------------------------------+
|i3 : degree ch                          |
|                                        |
|o3 = 5                                  |
+----------------------------------------+

The degree of classFunction(s_\lambda) always agrees with |\lambda|:

+------------------------------------------------------------+
|i4 : lam = {4,2,1};                                         |
+------------------------------------------------------------+
|i5 : degree classFunction(new Partition from lam) == sum lam|
|                                                            |
|o5 = true                                                   |
+------------------------------------------------------------+

A sum of characters of the same S_n keeps the same degree -- mixing distinct
partitions of 5 still yields a class function of degree 5:

+-----------------------------------------------------------------------------+
|i6 : R = symmetricRing(QQ,5);                                                |
+-----------------------------------------------------------------------------+
|i7 : mix = classFunction(jacobiTrudi({4,1},R)) +                             |
|-----------------------------------------------------------------------------|
|2*classFunction(jacobiTrudi({3,2},R));                                       |
+-----------------------------------------------------------------------------+
|i8 : degree mix                                                              |
|                                                                             |
|o8 = 5                                                                       |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * degree(ClassFunction) -- Degree of
    virtual character
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7084:0.

dim(List,SchurRingElement) -- dimension of representation
*********************************************************

  * Function: dim (Macaulay2Doc),
  * Usage:
        d = dim(lis,s)
        d = dim(n,s)
        d = dim s
  * Inputs:
      * lis, a list (Macaulay2Doc), or Thing (Macaulay2Doc),
      * s, an instance of the type SchurRingElement,
  * Outputs:
      * d, an integer (Macaulay2Doc), or Expression (Macaulay2Doc),

Description
===========

The method returns the dimension of the virtual representation whose character
is represented by s.

+-------------------------------------------+
|i1 : S = schurRing(s,3)                    |
|                                           |
|o1 = S                                     |
|                                           |
|o1 : SchurRing                             |
+-------------------------------------------+
|i2 : dim s_2                               |
|                                           |
|o2 = 6                                     |
+-------------------------------------------+
|i3 : T = schurRing(t,4,GroupActing => "Sn")|
|                                           |
|o3 = T                                     |
|                                           |
|o3 : SchurRing                             |
+-------------------------------------------+
|i4 : dim t_{2,2}                           |
|                                           |
|o4 = 2                                     |
+-------------------------------------------+
|i5 : U = schurRing(T,u,3)                  |
|                                           |
|o5 = U                                     |
|                                           |
|o5 : SchurRing                             |
+-------------------------------------------+
|i6 : dim (t_{2,2}*u_2)                     |
|                                           |
|o6 = 12                                    |
+-------------------------------------------+

Schur characters see the rank of the ambient vector space. The representation
s_{2,1} of GL(3) is 8-dimensional, while the same shape in GL(4) gives a
20-dimensional representation:

+----------------------------------+
|i7 : dim ((schurRing(s3,3))_{2,1})|
|                                  |
|o7 = 8                            |
+----------------------------------+
|i8 : dim ((schurRing(s4,4))_{2,1})|
|                                  |
|o8 = 20                           |
+----------------------------------+

Dimensions are also computed for symplectic and orthogonal characters.  For
orthogonal groups the option OddOrEven, selects O(2m+1) versus
O(2m):

+----------------------------------------------------------------------------+
|i9 : Sp = schurRing(QQ, sp, 3, GroupActing => "Sp");                        |
+----------------------------------------------------------------------------+
|i10 : dim sp_{2,1}                                                          |
|                                                                            |
|o10 = 64                                                                    |
+----------------------------------------------------------------------------+
|i11 : Oodd = schurRing(QQ, od, 3, GroupActing => "O", OddOrEven => "Odd");  |
+----------------------------------------------------------------------------+
|i12 : dim od_{2,1}                                                          |
|                                                                            |
|o12 = 105                                                                   |
+----------------------------------------------------------------------------+
|i13 : Oeven = schurRing(QQ, oe, 3, GroupActing => "O", OddOrEven => "Even");|
+----------------------------------------------------------------------------+
|i14 : dim oe_{2,1}                                                          |
|                                                                            |
|o14 = 64                                                                    |
+----------------------------------------------------------------------------+

If S is a SchurRing, of level 1, the ring of polynomial
representations of some GL(V), it may sometimes be convenient to compute
dimensions of GL(V)-representations symbolically, without specifying the
dimension of V.  Letting n denote the parameter corresponding to dim(V) we have
for example:

+--------------------------------+
|i15 : S = schurRing(s,3)        |
|                                |
|o15 = S                         |
|                                |
|o15 : SchurRing                 |
+--------------------------------+
|i16 : dim(n,s_2)                |
|                                |
|      n(n + 1)                  |
|o16 = --------                  |
|          2                     |
|                                |
|o16 : Expression of class Divide|
+--------------------------------+
|i17 : dim(n,s_{1,1})            |
|                                |
|      (n - 1)n                  |
|o17 = --------                  |
|          2                     |
|                                |
|o17 : Expression of class Divide|
+--------------------------------+
|i18 : dim(n,s_{2,1})            |
|                                |
|      (n - 1)n(n + 1)           |
|o18 = ---------------           |
|             3                  |
|                                |
|o18 : Expression of class Divide|
+--------------------------------+

Similar calculations make sense over products of general linear groups. The
dimensions of the representations can be computed symbolically as functions of
a number of parameters equal to the schurLevel, of the ring.
The parameters corresponding to levels where the group acting is a symmetric
group don't have a good interpretation, so they are disregarded in the
dimension calculation. The order of the input parameters is the descending
order of the schurLevel,s: in the example below a corresponds
to Q, b corresponds to T and c corresponds to S.

+------------------------------------------------+
|i19 : S = schurRing(s,3)                        |
|                                                |
|o19 = S                                         |
|                                                |
|o19 : SchurRing                                 |
+------------------------------------------------+
|i20 : T = schurRing(S,t,4)                      |
|                                                |
|o20 = T                                         |
|                                                |
|o20 : SchurRing                                 |
+------------------------------------------------+
|i21 : Q = schurRing(T,q,5,GroupActing => "Sn")  |
|                                                |
|o21 = Q                                         |
|                                                |
|o21 : SchurRing                                 |
+------------------------------------------------+
|i22 : dExpr = dim({a,b,c},s_{2}*t_{1,1}*q_{4,1})|
|                                                |
|      c(c + 1) (b - 1)b                         |
|o22 = --------*--------*4                       |
|          2        2                            |
|                                                |
|o22 : Expression of class Product               |
+------------------------------------------------+
|i23 : P = QQ[a,b,c]                             |
|                                                |
|o23 = P                                         |
|                                                |
|o23 : PolynomialRing                            |
+------------------------------------------------+
|i24 : value dExpr                               |
|                                                |
|       2 2    2       2                         |
|o24 = b c  + b c - b*c  - b*c                   |
|                                                |
|o24 : P                                         |
+------------------------------------------------+
|i25 : dim({1,2,3},s_{2}*t_{1,1}*q_{4,1})        |
|                                                |
|o25 = 24                                        |
|                                                |
|o25 : QQ                                        |
+------------------------------------------------+

Over a two-level GL\times GL tower the formula factors as a product of
dimensions, one per level, in descending schurLevel order:

+-------------------------------------+
|i26 : A = schurRing(aR,3);           |
+-------------------------------------+
|i27 : B = schurRing(A,bR,2);         |
+-------------------------------------+
|i28 : dim(aR_{2,1} * bR_{1,1})       |
|                                     |
|o28 = 8                              |
+-------------------------------------+
|i29 : dim({4,5}, aR_{2,1} * bR_{1,1})|
|                                     |
|o29 = 240                            |
|                                     |
|o29 : QQ                             |
+-------------------------------------+

Ways to use this method:
========================

  * dim(List,SchurRingElement), --
    dimension of representation
  * "dim(SchurRingElement)"
  * "dim(Thing,SchurRingElement)"
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6960:0.

EHPVariables -- Specifies sequence of symbols representing e-, h-, and p-functions
**********************************************************************************

Description
===========

This is an optional argument for the constructor of a Symmetric or Schur ring.
It indicates the symbols to be used to denote e-, h-, and p-functions in the
associated Symmetric ring. The default values are (e,h,p).

+-----------------------------------------------------------------------------+
|i1 : S = schurRing(QQ,s,4,EHPVariables =>                                    |
|-----------------------------------------------------------------------------|
|(getSymbol"a",getSymbol"b",getSymbol"c"));                                   |
+-----------------------------------------------------------------------------+
|i2 : R = symmetricRing S                                                     |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : epol = toE s_{2,2,2}                                                    |
|                                                                             |
|      2                                                                      |
|o3 = a  - a a                                                                |
|      3    2 4                                                               |
|                                                                             |
|o3 : R                                                                       |
+-----------------------------------------------------------------------------+
|i4 : toS epol                                                                |
|                                                                             |
|o4 = s                                                                       |
|      2,2,2                                                                  |
|                                                                             |
|o4 : S                                                                       |
+-----------------------------------------------------------------------------+

The three symbols become the polynomial-ring generators of the associated
symmetricRing.  With the default (e,h,p), inspecting gens shows
all three families indexed by 1..n:

+-----------------------------------------+
|i5 : R = symmetricRing(QQ,3);            |
+-----------------------------------------+
|i6 : gens R                              |
|                                         |
|o6 = {e , e , e , p , p , p , h , h , h }|
|       1   2   3   1   2   3   1   2   3 |
|                                         |
|o6 : List                                |
+-----------------------------------------+

A custom triple works the same way.  Below, a_i, c_i, b_i correspond
respectively to the elementary, power-sum and complete homogeneous symmetric
functions in the associated Symmetric ring:

+-----------------------------------------------------------------------------+
|i7 : S2 = schurRing(QQ,s,4,EHPVariables =>                                   |
|-----------------------------------------------------------------------------|
|(getSymbol"a",getSymbol"b",getSymbol"c"));                                   |
+-----------------------------------------------------------------------------+
|i8 : R2 = symmetricRing S2;                                                  |
+-----------------------------------------------------------------------------+
|i9 : gens R2                                                                 |
|                                                                             |
|o9 = {a , a , a , a , c , c , c , c , b , b , b , b }                        |
|       1   2   3   4   1   2   3   4   1   2   3   4                         |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+

The option propagates across tensor products of Schur rings, so each factor may
carry its own e/h/p alphabet without name clashes:

+-----------------------------------------------------------------------------+
|i10 : A = schurRing(QQ,sa,3,EHPVariables =>                                  |
|-----------------------------------------------------------------------------|
|(getSymbol"ea",getSymbol"ha",getSymbol"pa"));                                |
+-----------------------------------------------------------------------------+
|i11 : B = schurRing(A,sb,2,EHPVariables =>                                   |
|-----------------------------------------------------------------------------|
|(getSymbol"eb",getSymbol"hb",getSymbol"pb"));                                |
+-----------------------------------------------------------------------------+
|i12 : schurLevel B                                                           |
|                                                                             |
|o12 = 2                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * SVariable -- Specifies symbol representing s-functions

Functions with optional argument named EHPVariables:
====================================================

  * "schurRing(...,EHPVariables=>...)"
  * "symmetricRing(...,EHPVariables=>...)"

For the programmer
==================

The object EHPVariables, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7819:0.

EorH -- e- or h- representation of Jacobi-Trudi determinant
***********************************************************

  * Usage:
        EorH => s
  * Inputs:
      * s, a string (Macaulay2Doc), either "E" or "H"

Description
===========

This option allows one to choose between evaluating the Jacobi-Trudi
determinant in the e- or h- basis. If the length of the conjugate partition
lambda' is larger than the length of lambda, then it is computationally less
expensive to set the option EorH to "H". Otherwise, the default value "E" is
more efficient.

+-----------------------------------------------------------------------------+
|i1 : R = symmetricRing(QQ,8);                                                |
+-----------------------------------------------------------------------------+
|i2 : fe = jacobiTrudi({2,2,2,2,2},R,EorH => "E");                            |
+-----------------------------------------------------------------------------+
|i3 : fh = jacobiTrudi({2,2,2,2,2},R,EorH => "H");                            |
+-----------------------------------------------------------------------------+
|i4 : fe                                                                      |
|                                                                             |
|      2                                                                      |
|o4 = e  - e e                                                                |
|      5    4 6                                                               |
|                                                                             |
|o4 : R                                                                       |
+-----------------------------------------------------------------------------+
|i5 : fh                                                                      |
|                                                                             |
|      5       3       2   2     2 2       3     2 2       3       3          |
|o5 = h  - 4h h h  + 3h h h  + 3h h  - 2h h  + 3h h h  - 3h h  - 2h h h  -    |
|      2     1 2 3     1 2 3     2 3     1 3     1 2 4     2 4     1 3 4      |
|     ------------------------------------------------------------------------|
|                  2      2 2       2     3           2       2               |
|     2h h h h  + h h  + h h  + 2h h  - 2h h h  + 4h h h  + 2h h h  - 4h h h  |
|       1 2 3 4    3 4    1 4     2 4     1 2 5     1 2 5     1 3 5     2 3 5 |
|     ------------------------------------------------------------------------|
|                  2    4       2        2                                    |
|     - 2h h h  + h  + h h  - 3h h h  + h h  + 2h h h  - h h                  |
|         1 4 5    5    1 6     1 2 6    2 6     1 3 6    4 6                 |
|                                                                             |
|o5 : R                                                                       |
+-----------------------------------------------------------------------------+

Although the two polynomials are superficially different, they are equal as
symmetric functions, as seen after applying toS,:

+---------------------+
|i6 : toS fe == toS fh|
|                     |
|o6 = true            |
+---------------------+

When the conjugate partition is much longer than lambda itself, the "H"-branch
requires a smaller determinant and runs measurably faster.  For example on
lambda = (10) the conjugate is $(1^{10})$, so "H" only sets up a 1x1
determinant:

+------------------------------------------------------------------+
|i7 : R = symmetricRing(QQ,12);                                    |
+------------------------------------------------------------------+
|i8 : elapsedTime jacobiTrudi({10},R,EorH => "E",Memoize => false);|
| -- .00514868s elapsed                                            |
+------------------------------------------------------------------+
|i9 : elapsedTime jacobiTrudi({10},R,EorH => "H",Memoize => false);|
| -- .000188454s elapsed                                           |
+------------------------------------------------------------------+

Functions with optional argument named EorH:
============================================

  * "jacobiTrudi(...,EorH=>...)"

For the programmer
==================

The object EorH, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6153:0.

eVariable -- Elementary symmetric functions in a Symmetric ring
***************************************************************

Description
===========

For a Symmetric ring R of dimension n, R.eVariable is a function which assigns
to each index 1\leq i\leq n the i-th elementary symmetric function. If i is
outside the given bounds, an error is returned.

+-----------------------------------------------------+
|i1 : R = symmetricRing(QQ,5,EHPVariables => (a,b,c));|
+-----------------------------------------------------+
|i2 : R.eVariable 3                                   |
|                                                     |
|o2 = a                                               |
|      3                                              |
|                                                     |
|o2 : R                                               |
+-----------------------------------------------------+

The elementary generators are related to the Schur basis via e_k = s_{1^k};
see toS, realizes this on any product of e-variables.

+-----------------------------+
|i3 : R = symmetricRing(QQ,4);|
+-----------------------------+
|i4 : toS (R.eVariable 2)     |
|                             |
|o4 = s                       |
|      1,1                    |
|                             |
|o4 : schurRing (QQ, s, 4)    |
+-----------------------------+
|i5 : toS ((R.eVariable 2)^2) |
|                             |
|o5 = s    + s      + s       |
|      2,2    2,1,1    1,1,1,1|
|                             |
|o5 : schurRing (QQ, s, 4)    |
+-----------------------------+

One may also use eVariable from a Symmetric ring built with a non-standard
coefficient ring or group acting on it.

+---------------------------------------------------+
|i6 : Rsn = symmetricRing(QQ,4,GroupActing => "Sn");|
+---------------------------------------------------+
|i7 : toS symmetricPower(2, Rsn.eVariable 2)        |
|                                                   |
|o7 = s                                             |
|      2                                            |
|                                                   |
|o7 : schurRing (QQ, s, 4)                          |
+---------------------------------------------------+
|i8 : Rmod = symmetricRing(ZZ/5,3);                 |
+---------------------------------------------------+
|i9 : (Rmod.eVariable 1)^5                          |
|                                                   |
|      5                                            |
|o9 = e                                             |
|      1                                            |
|                                                   |
|o9 : Rmod                                          |
+---------------------------------------------------+

See also
========

  * hVariable -- Complete symmetric functions in a Symmetric
    ring
  * pVariable -- Power-sum symmetric functions in a Symmetric
    ring
  * symmetricRing -- Make a Symmetric ring
  * toS -- Schur (s-) basis representation

For the programmer
==================

The object eVariable, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5355:0.

GroupActing -- Specifies the group that is acting
*************************************************

Description
===========

This is an optional argument for the schurRing, and
symmetricRing, functions. When the exterior or symmetric powers
of a symmetric function g are computed, the result depends on whether g is
interpreted as a virtual representation of a general linear, symmetric,
symplectic, or orthogonal group. The option GroupActing specifies the
interpretation to be considered. Its possible values are "GL" (the default),
"Sn", "SL", "Sp", "O", and "RatGL".

+--------------------------------------------+
|i1 : S = schurRing(s,2);                    |
+--------------------------------------------+
|i2 : exteriorPower(3,s_2)                   |
|                                            |
|o2 = s                                      |
|      3,3                                   |
|                                            |
|o2 : S                                      |
+--------------------------------------------+
|i3 : T = schurRing(t,2,GroupActing => "Sn");|
+--------------------------------------------+
|i4 : symmetricPower(2,t_{1,1})              |
|                                            |
|o4 = t                                      |
|      2                                     |
|                                            |
|o4 : T                                      |
+--------------------------------------------+

The first example computes the decomposition of \Lambda^3(Sym^2(V)) into
irreducible GL(V)-representations, while the second one computes the second
symmetric power of the sign representation of the symmetric group S_2.

Multiplication differs sharply between the "GL" and "Sn" interpretations.
Under "GL", the product is the Littlewood-Richardson tensor product of
polynomial representations, which is degree-additive in the partitions. Under
"Sn", multiplication is the ordinary tensor product of characters of a single
symmetric group, so only partitions of the same size may be multiplied, and the
product is expanded in the Kronecker coefficients:

+------------------------------------------------------------------+
|i5 : Sgl = schurRing(QQ,s,4);                                     |
+------------------------------------------------------------------+
|i6 : s_{2,1} * s_{2,1}                                            |
|                                                                  |
|o6 = s    + s      + s    + 2s      + s        + s      + s       |
|      4,2    4,1,1    3,3     3,2,1    3,1,1,1    2,2,2    2,2,1,1|
|                                                                  |
|o6 : Sgl                                                          |
+------------------------------------------------------------------+
|i7 : Ssn = schurRing(QQ,t,4,GroupActing => "Sn");                 |
+------------------------------------------------------------------+
|i8 : t_{2,1,1} * t_{2,1,1}                                        |
|                                                                  |
|o8 = t  + t    + t    + t                                         |
|      4    3,1    2,2    2,1,1                                    |
|                                                                  |
|o8 : Ssn                                                          |
+------------------------------------------------------------------+

The values "Sp" and "O" select the stable (universal) character ring of the
symplectic and orthogonal groups, respectively. The basis elements are indexed
by partitions, with sp_\lambda (respectively o_\lambda) standing for the
irreducible symplectic (respectively orthogonal) character associated to
\lambda. Multiplication in these rings is the Newell-Littlewood product,
implemented by conversion to the Schur basis via Koike's branching formulas and
back:

+-----------------------------------------------+
|i9 : Sp = schurRing(QQ,sp,GroupActing => "Sp");|
+-----------------------------------------------+
|i10 : sp_{1} * sp_{1}                          |
|                                               |
|o10 = sp  + sp    + sp                         |
|        2     1,1     ()                       |
|                                               |
|o10 : Sp                                       |
+-----------------------------------------------+
|i11 : sp_{1,1}                                 |
|                                               |
|o11 = sp                                       |
|        1,1                                    |
|                                               |
|o11 : Sp                                       |
+-----------------------------------------------+
|i12 : toS sp_{1,1}                             |
|                                               |
|o12 = s    - s                                 |
|       1,1    ()                               |
|                                               |
|o12 : schurRing (QQ, s, infinity)              |
+-----------------------------------------------+
|i13 : O = schurRing(QQ,o,GroupActing => "O");  |
+-----------------------------------------------+
|i14 : o_{1} * o_{1}                            |
|                                               |
|o14 = o  + o    + o                            |
|       2    1,1    ()                          |
|                                               |
|o14 : O                                        |
+-----------------------------------------------+
|i15 : toS o_{2}                                |
|                                               |
|o15 = s  - s                                   |
|       2    ()                                 |
|                                               |
|o15 : schurRing (QQ, s, infinity)              |
+-----------------------------------------------+

Exterior and symmetric powers are likewise reinterpreted. In the orthogonal
ring, exterior powers of the second fundamental character mix several
Newell-Littlewood terms:

+---------------------------------------------------------+
|i16 : Ofin = schurRing(QQ,obar,5,GroupActing => "O");    |
+---------------------------------------------------------+
|i17 : exteriorPower(3, obar_2)                           |
|                                                         |
|o17 = obar      + obar    + obar    + obar      + obar   |
|          4,1,1       3,3       3,1       2,1,1       1,1|
|                                                         |
|o17 : Ofin                                               |
+---------------------------------------------------------+

Setting GroupActing => "SL" forces the top-row reduction s_\lambda =
s_{(\lambda_1 - \lambda_n, \ldots, \lambda_{n-1} - \lambda_n)}, reflecting the
fact that the determinant representation is trivial in SL.  Long partitions
collapse accordingly:

+---------------------------------------------------+
|i18 : SL3 = schurRing(QQ,sl,3,GroupActing => "SL");|
+---------------------------------------------------+
|i19 : sl_{3,2,1}                                   |
|                                                   |
|o19 = sl                                           |
|        2,1                                        |
|                                                   |
|o19 : SL3                                          |
+---------------------------------------------------+
|i20 : sl_{4,2,2}                                   |
|                                                   |
|o20 = sl                                           |
|        2                                          |
|                                                   |
|o20 : SL3                                          |
+---------------------------------------------------+
|i21 : sl_{2,1,1}                                   |
|                                                   |
|o21 = sl                                           |
|        1                                          |
|                                                   |
|o21 : SL3                                          |
+---------------------------------------------------+

Finally, GroupActing => "RatGL" produces the ring of rational (mixed)
polynomial representations of GL(V), whose characters are indexed by pairs of
partitions (bipartitions), and whose tensor product is again a
Littlewood-Richardson-style rule:

+----------------------------------------------------+
|i22 : Rg = schurRing(QQ,r,3,GroupActing => "RatGL");|
+----------------------------------------------------+
|i23 : r_({1},{}) * r_({},{1})                       |
|                                                    |
|o23 = r           + r                               |
|       {{1}, {1}}    {{}, {}}                       |
|                                                    |
|o23 : Rg                                            |
+----------------------------------------------------+

Stable rings (no dimension specified) allow arbitrarily many parts in the
partition labels; a concrete dimension can be supplied to restrict the
partitions and to model a finite-dimensional group.

See also
========

  * toSp -- Expansion in the basis of symplectic characters
  * toO -- Expansion in the basis of orthogonal characters
  * toS -- Schur (s-) basis representation

Functions with optional argument named GroupActing:
===================================================

  * "schurRing(...,GroupActing=>...)"
  * "symmetricRing(...,GroupActing=>...)"

For the programmer
==================

The object GroupActing, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7927:0.

hVariable -- Complete symmetric functions in a Symmetric ring
*************************************************************

Description
===========

For a Symmetric ring R of dimension n, R.hVariable is a function which assigns
to each index 1\leq i\leq n the i-th complete symmetric function. If i is
outside the given bounds, an error is returned.

+-----------------------------------------------------+
|i1 : R = symmetricRing(QQ,2,EHPVariables => (x,y,z));|
+-----------------------------------------------------+
|i2 : R.hVariable 2                                   |
|                                                     |
|o2 = y                                               |
|      2                                              |
|                                                     |
|o2 : R                                               |
+-----------------------------------------------------+

Complete symmetric functions translate to one-row Schur functions via h_k =
s_k; this is the other half of the e/h-duality.

+----------------------------------------+
|i3 : R = symmetricRing(QQ,4);           |
+----------------------------------------+
|i4 : toS (R.hVariable 3)                |
|                                        |
|o4 = s                                  |
|      3                                 |
|                                        |
|o4 : schurRing (QQ, s, 4)               |
+----------------------------------------+
|i5 : toS (R.eVariable 2 * R.hVariable 2)|
|                                        |
|o5 = s    + s                           |
|      3,1    2,1,1                      |
|                                        |
|o5 : schurRing (QQ, s, 4)               |
+----------------------------------------+

They interact cleanly with power sums: Newton's identities are realized by
toE, and toP, and here we convert a cube of h_2 into the
power-sum basis.

+-----------------------------+
|i6 : R = symmetricRing(QQ,3);|
+-----------------------------+
|i7 : toP ((R.hVariable 2)^2) |
|                             |
|     1 4   1 2     1 2       |
|o7 = -p  + -p p  + -p        |
|     4 1   2 1 2   4 2       |
|                             |
|o7 : R                       |
+-----------------------------+

Complete symmetric functions are available over any coefficient ring.

+----------------------------------------------+
|i8 : Rt = symmetricRing(QQ[t],3);             |
+----------------------------------------------+
|i9 : toS (Rt.hVariable 2 + t * Rt.eVariable 2)|
|                                              |
|o9 = s  + t*s                                 |
|      2      1,1                              |
|                                              |
|o9 : schurRing (QQ[t], s, 3)                  |
+----------------------------------------------+

See also
========

  * eVariable -- Elementary symmetric functions in a
    Symmetric ring
  * pVariable -- Power-sum symmetric functions in a Symmetric
    ring
  * symmetricRing -- Make a Symmetric ring
  * toS -- Schur (s-) basis representation

For the programmer
==================

The object hVariable, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5405:0.

internalProduct -- Internal product of symmetric functions/class functions
**************************************************************************

Description
===========

This method computes the internal (Kronecker) product of two homogeneous
symmetric functions of the same degree.  If we think of these functions as
virtual characters of some symmetric group, then their internal product is just
the character of the tensor product of the corresponding virtual
representations.  We use the binary operator ** (Macaulay2Doc), as
a shorthand for internalProduct.

The complete symmetric function of degree n corresponds to the trivial
S_n-representation and is therefore the unit of the representation ring of S_n:

+---------------------------------+
|i1 : R = symmetricRing(QQ,5);    |
+---------------------------------+
|i2 : S = schurRing(QQ,s,3);      |
+---------------------------------+
|i3 : internalProduct(h_3,s_{2,1})|
|                                 |
|o3 = s                           |
|      2,1                        |
|                                 |
|o3 : S                           |
+---------------------------------+
|i4 : toE(h_3 ** e_3)             |
|                                 |
|o4 = e                           |
|      3                          |
|                                 |
|o4 : QQ[e ..e , p ..p , h ..h ]  |
|         1   3   1   3   1   3   |
+---------------------------------+

The square of the sign representation is the trivial representation:

+---------------------------------+
|i5 : toH internalProduct(e_3,e_3)|
|                                 |
|o5 = h                           |
|      3                          |
|                                 |
|o5 : QQ[e ..e , p ..p , h ..h ]  |
|         1   3   1   3   1   3   |
+---------------------------------+

Working in a Schur ring directly, Kronecker products of Schur functions give
the decomposition of tensor products of irreducible S_n-representations.  The
Kronecker square of s_{2,1} (the standard representation of S_3) decomposes as:

+--------------------------------------+
|i6 : T = schurRing(QQ,t,3);           |
+--------------------------------------+
|i7 : internalProduct(t_{2,1}, t_{2,1})|
|                                      |
|o7 = t  + t    + t                    |
|      3    2,1    1,1,1               |
|                                      |
|o7 : T                                |
+--------------------------------------+

The exterior square of the sign representation of S_3 is the trivial
representation, which on the symmetric-function side is the identity s_{1,1,1}
\otimes s_{1,1,1} = s_3:

+------------------------------------------+
|i8 : internalProduct(t_{1,1,1}, t_{1,1,1})|
|                                          |
|o8 = t                                    |
|      3                                   |
|                                          |
|o8 : T                                    |
+------------------------------------------+

See also
========

  * scalarProduct -- Standard pairing on symmetric
    functions/class functions

Ways to use internalProduct:
============================

  * internalProduct(ClassFunction,ClassFunction)
    -- Tensor product of
    virtual representations
  * internalProduct(RingElement,RingElement)
    -- Kronecker product of
    symmetric functions

For the programmer
==================

The object internalProduct, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7502:0.

internalProduct(ClassFunction,ClassFunction) -- Tensor product of virtual representations
*****************************************************************************************

  * Function: internalProduct,
  * Usage:
        ip = internalProduct(ch1,ch2)
  * Inputs:
      * ch1, a Class function,
      * ch2, a Class function,
  * Outputs:
      * ip, a Class function,

Description
===========

Given virtual characters ch1 and ch2, the method computes the character of the
tensor product of corresponding virtual representations of the symmetric group.

+-----------------------------------------------------------------------------+
|i1 : ch1 = new ClassFunction from {{4,4} => 2, {8} => -1, {5,2,1} => 2,      |
|-----------------------------------------------------------------------------|
|{3,2,2,1} => 1};                                                             |
+-----------------------------------------------------------------------------+
|i2 : ch2 = new ClassFunction from {{2,2,2,2} => -4, {5,2,1} => 1, {3,2,2,1}  |
|-----------------------------------------------------------------------------|
|=> 3};                                                                       |
+-----------------------------------------------------------------------------+
|i3 : internalProduct(ch1,ch2)                                                |
|                                                                             |
|o3 = ClassFunction{{3, 2, 2, 1} => 3}                                        |
|                   {5, 2, 1} => 2                                            |
|                                                                             |
|o3 : ClassFunction                                                           |
+-----------------------------------------------------------------------------+
|i4 : ch1 * ch2                                                               |
|                                                                             |
|o4 = ClassFunction{{3, 2, 2, 1} => 3}                                        |
|                   {5, 2, 1} => 2                                            |
|                                                                             |
|o4 : ClassFunction                                                           |
+-----------------------------------------------------------------------------+

A classical example: the tensor square of the standard representation of S_4
has character values obtained by squaring the standard character.  Pairing with
itself recovers the multiplicities of the irreducibles in the tensor square:

+------------------------------------------------+
|i5 : S = schurRing(QQ,s,4);                     |
+------------------------------------------------+
|i6 : std = classFunction s_{3,1};               |
+------------------------------------------------+
|i7 : sq = internalProduct(std, std)             |
|                                                |
|o7 = ClassFunction{{1, 1, 1, 1} => 9}           |
|                   {2, 1, 1} => 1               |
|                   {2, 2} => 1                  |
|                   {4} => 1                     |
|                                                |
|o7 : ClassFunction                              |
+------------------------------------------------+
|i8 : scalarProduct(sq, classFunction s_{4})     |
|                                                |
|o8 = 1                                          |
|                                                |
|o8 : QQ                                         |
+------------------------------------------------+
|i9 : scalarProduct(sq, classFunction s_{3,1})   |
|                                                |
|o9 = 1                                          |
|                                                |
|o9 : QQ                                         |
+------------------------------------------------+
|i10 : scalarProduct(sq, classFunction s_{2,2})  |
|                                                |
|o10 = 1                                         |
|                                                |
|o10 : QQ                                        |
+------------------------------------------------+
|i11 : scalarProduct(sq, classFunction s_{2,1,1})|
|                                                |
|o11 = 1                                         |
|                                                |
|o11 : QQ                                        |
+------------------------------------------------+

See also
========

  * classFunction -- Converts symmetric function to class
    function

Ways to use this method:
========================

  * internalProduct(ClassFunction,ClassFunction)
    -- Tensor product of
    virtual representations
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7610:0.

internalProduct(RingElement,RingElement) -- Kronecker product of symmetric functions
************************************************************************************

  * Function: internalProduct,
  * Usage:
        ip = internalProduct(f1,f2)
  * Inputs:
      * f1, a ring element (Macaulay2Doc), element of a
        Symmetric ring or a Schur ring
      * f2, a ring element (Macaulay2Doc), element of a
        Symmetric ring or a Schur ring
  * Outputs:
      * ip, a ring (Macaulay2Doc), a Symmetric ring or a Schur Ring

Description
===========

Given symmetric functions f1 and f2, the method computes the Kronecker product
ip between f1 and f2. The output ip is an element in the ring of f2.

+---------------------------------------------+
|i1 : R = symmetricRing(QQ,6);                |
+---------------------------------------------+
|i2 : S = schurRing(QQ,s,6);                  |
+---------------------------------------------+
|i3 : toE(h_3**e_3)                           |
|                                             |
|o3 = e                                       |
|      3                                      |
|                                             |
|o3 : R                                       |
+---------------------------------------------+
|i4 : Q = schurRing(QQ,q,6);                  |
+---------------------------------------------+
|i5 : internalProduct(s_{3,3},q_{4,2})        |
|                                             |
|o5 = q    + q      + q    + q      + q       |
|      5,1    4,1,1    3,3    3,2,1    2,2,1,1|
|                                             |
|o5 : Q                                       |
+---------------------------------------------+

An error is returned if f1 and f2 don't have the same degree.

Products of complete homogeneous functions give characters of permutation
representations of S_n; their Kronecker product decomposes accordingly.  For
instance, in degree 4:

+--------------------------------------+
|i6 : internalProduct(h_3*h_1, h_2*h_2)|
|                                      |
|      4    2                          |
|o6 = p  + p p                         |
|      1    1 2                        |
|                                      |
|o6 : QQ[e ..e , p ..p , h ..h ]       |
|         1   6   1   6   1   6        |
+--------------------------------------+

The same computation can be carried out directly in a Schur ring with option
GroupActing => "Sn", where multiplication * is the internal product.  The
Kronecker square of the standard representation s_{3,1} of S_4 decomposes as
trivial + sign + standard + s_{2,2}:

+------------------------------------------------+
|i7 : Sn = schurRing(QQ,c,4,GroupActing => "Sn");|
+------------------------------------------------+
|i8 : c_{3,1} * c_{3,1}                          |
|                                                |
|o8 = c  + c    + c    + c                       |
|      4    3,1    2,2    2,1,1                  |
|                                                |
|o8 : Sn                                         |
+------------------------------------------------+
|i9 : internalProduct(c_{3,1}, c_{3,1})          |
|                                                |
|o9 = c  + c    + c    + c                       |
|      4    3,1    2,2    2,1,1                  |
|                                                |
|o9 : Sn                                         |
+------------------------------------------------+

The method is compatible with toSn,: we can first convert a product
of h's into the Schur basis of an S_n ring, then take Kronecker products there.

+----------------------------------------------+
|i10 : toSn(h_2*h_1*h_1, Sn) * c_{3,1}         |
|                                              |
|o10 = 2c  + 5c    + 3c    + 4c      + c       |
|        4     3,1     2,2     2,1,1    1,1,1,1|
|                                              |
|o10 : Sn                                      |
+----------------------------------------------+

Ways to use this method:
========================

  * internalProduct(RingElement,RingElement)
    -- Kronecker product of
    symmetric functions
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7566:0.

jacobiTrudi -- Jacobi-Trudi determinant
***************************************

  * Usage:
        f = jacobiTrudi(lambda,R)
  * Inputs:
      * lambda, a basic list (Macaulay2Doc), a nonincreasing
        list of integers, or a partition
      * R, a ring (Macaulay2Doc), a Symmetric ring
  * Optional inputs (Macaulay2Doc),:
      * EorH, => ..., default value "E", e- or h- representation of
        Jacobi-Trudi determinant
      * Memoize, => ...,
        default value true, Store values of the jacobiTrudi function.
  * Outputs:
      * f, a ring element (Macaulay2Doc), an element of a
        Symmetric ring

Description
===========

Given a partition lambda and Symmetric ring R, the method evaluates the
Jacobi-Trudi determinant corresponding to the partition lambda, yielding a
representation of the Schur function s_{lambda} as a symmetric function in R.
The default option is to represent this symmetric function in terms of
e-polynomials.

+----------------------------------------------------------+
|i1 : R = symmetricRing(QQ,10);                            |
+----------------------------------------------------------+
|i2 : jacobiTrudi({3,2,2,1},R)                             |
|                                                          |
|               2                                          |
|o2 = e e e  - e  - e e e  + e e                           |
|      1 3 4    4    1 2 5    2 6                          |
|                                                          |
|o2 : R                                                    |
+----------------------------------------------------------+
|i3 : jacobiTrudi(new Partition from {4,4,1},R,EorH => "H")|
|                                                          |
|        2                                                 |
|o3 = h h  - h h h  - h h  + h h                           |
|      1 4    1 3 5    4 5    3 6                          |
|                                                          |
|o3 : R                                                    |
+----------------------------------------------------------+
|i4 : toS oo                                               |
|                                                          |
|o4 = s                                                    |
|      4,4,1                                               |
|                                                          |
|o4 : schurRing (QQ, s, 10)                                |
+----------------------------------------------------------+

Selecting EorH => "H" uses the conjugate determinant formula $s_\lambda =
\det(h_{\lambda_i - i + j})$.  The two branches produce different e- vs
h-polynomials but always represent the same Schur function:

+-----------------------------------------+
|i5 : R = symmetricRing(QQ,8);            |
+-----------------------------------------+
|i6 : lam = {4,3,2,1};                    |
+-----------------------------------------+
|i7 : fe = jacobiTrudi(lam,R,EorH => "E");|
+-----------------------------------------+
|i8 : fh = jacobiTrudi(lam,R,EorH => "H");|
+-----------------------------------------+
|i9 : toS fe                              |
|                                         |
|o9 = s                                   |
|      4,3,2,1                            |
|                                         |
|o9 : schurRing (QQ, s, 8)                |
+-----------------------------------------+
|i10 : toS fh                             |
|                                         |
|o10 = s                                  |
|       4,3,2,1                           |
|                                         |
|o10 : schurRing (QQ, s, 8)               |
+-----------------------------------------+
|i11 : toS fe == toS fh                   |
|                                         |
|o11 = true                               |
+-----------------------------------------+

The routine caches intermediate subdeterminants on the ring via
jacobiTrudi(...,Memoize=>...),
so a second call on a large
partition returns almost instantly:

+-------------------------------------------+
|i12 : R = symmetricRing(QQ,6);             |
+-------------------------------------------+
|i13 : elapsedTime jacobiTrudi({4,3,2,1},R);|
| -- .000460013s elapsed                    |
+-------------------------------------------+
|i14 : elapsedTime jacobiTrudi({4,3,2,1},R);|
| -- .000018138s elapsed                    |
+-------------------------------------------+

Passing a partition through toSymm, applied to the corresponding
Schur label reproduces the Jacobi-Trudi output:

+-------------------------------------------------+
|i15 : R = symmetricRing(QQ,5);                   |
+-------------------------------------------------+
|i16 : S = schurRing R;                           |
+-------------------------------------------------+
|i17 : jacobiTrudi({3,2,1},R) == toSymm(S_{3,2,1})|
|                                                 |
|o17 = true                                       |
+-------------------------------------------------+

jacobiTrudi works over tensor products of Symmetric rings, producing a
determinant in the outermost set of generators:

+--------------------------------------------------------+
|i18 : R = symmetricRing(QQ, 4, EHPVariables => (a,b,c));|
+--------------------------------------------------------+
|i19 : T = symmetricRing(R, 3, EHPVariables => (x,y,z)); |
+--------------------------------------------------------+
|i20 : jacobiTrudi({2,1},T)                              |
|                                                        |
|o20 = x x  - x                                          |
|       1 2    3                                         |
|                                                        |
|o20 : T                                                 |
+--------------------------------------------------------+
|i21 : jacobiTrudi({3,2},T, EorH => "H")                 |
|                                                        |
|o21 = y y                                               |
|       2 3                                              |
|                                                        |
|o21 : T                                                 |
+--------------------------------------------------------+

Ways to use jacobiTrudi:
========================

  * "jacobiTrudi(BasicList,Ring)"

For the programmer
==================

The object jacobiTrudi, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6102:0.

jacobiTrudi(...,Memoize=>...) -- Store values of the jacobiTrudi function.
**************************************************************************

  * Usage:
        Memoize => b
  * Inputs:
      * b, a Boolean value (Macaulay2Doc),

Description
===========

If the option is set to true then all the values of the jacobiTrudi function
that are computed are recorded into a special hash table attached to the
symmetric ring inside which the computations are done.  This makes repeated
evaluations on related partitions substantially faster, at the cost of some
extra memory in the ring.

+-----------------------------------------------------------------------------+
|i1 : R = symmetricRing(QQ,6);                                                |
+-----------------------------------------------------------------------------+
|i2 : jacobiTrudi({4,3,2,1},R,Memoize => true) ==                             |
|                                                                             |
|o2 = true                                                                    |
|-----------------------------------------------------------------------------|
|jacobiTrudi({4,3,2,1},R,Memoize => false)                                    |
+-----------------------------------------------------------------------------+
|i3 : elapsedTime jacobiTrudi({5,4,3,2,1},R,Memoize => true);                 |
| -- .000542437s elapsed                                                      |
+-----------------------------------------------------------------------------+
|i4 : elapsedTime jacobiTrudi({5,4,3,2,1},R,Memoize => true);                 |
| -- .000018007s elapsed                                                      |
+-----------------------------------------------------------------------------+
|i5 : elapsedTime jacobiTrudi({5,4,3,2,1},R,Memoize => false);                |
| -- .0004387s elapsed                                                        |
+-----------------------------------------------------------------------------+

Functions with optional argument named Memoize:
===============================================

  * jacobiTrudi(...,Memoize=>...)
    -- Store values of the
    jacobiTrudi function.

Further information
===================

  * Default value: true (Macaulay2Doc),
  * Function: jacobiTrudi, -- Jacobi-Trudi determinant
  * Option key: Memoize, -- Option to record values of the
    jacobiTrudi function
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6179:0.

kostkaNumber -- Compute a Kostka number
***************************************

  * Usage:
        k = kostkaNumber(lambda,mu)
  * Inputs:
      * lambda, a basic list (Macaulay2Doc), a partition
      * mu, a basic list (Macaulay2Doc), a composition (or
        partition) of the same size as lambda
  * Outputs:
      * k, an integer (Macaulay2Doc), the Kostka number
        K_{\lambda,\mu}

Description
===========

The Kostka number K_{\lambda,\mu} is the number of semistandard Young tableaux
of shape \lambda and content \mu. Equivalently, it is the coefficient of the
Schur function s_\lambda in the product of complete symmetric functions
h_{\mu_1} h_{\mu_2} \cdots.

+--------------------------------+
|i1 : kostkaNumber({2,1},{1,1,1})|
|                                |
|o1 = 2                          |
+--------------------------------+
|i2 : kostkaNumber({3},{2,1})    |
|                                |
|o2 = 1                          |
+--------------------------------+
|i3 : kostkaNumber({2,1},{2,1})  |
|                                |
|o3 = 1                          |
+--------------------------------+
|i4 : kostkaNumber({2,1},{3})    |
|                                |
|o4 = 0                          |
+--------------------------------+

Returns 0 whenever \lambda and \mu do not have the same size, or whenever \mu
does not dominate \lambda (so that no tableaux of the requested shape and
content exist).

The full Kostka matrix K_{\lambda,\mu} for partitions of 4, listed in reverse
dominance order (4), (3,1), (2,2), (2,1,1), (1,1,1,1), is upper triangular with
ones on the diagonal (a reflection of the fact that Schur functions form an
h-triangular basis with respect to the monomial basis):

+---------------------------------------------------------------+
|i5 : P = {{4},{3,1},{2,2},{2,1,1},{1,1,1,1}};                  |
+---------------------------------------------------------------+
|i6 : matrix apply(P, la -> apply(P, mu -> kostkaNumber(la,mu)))|
|                                                               |
|o6 = | 1 1 1 1 1 |                                             |
|     | 0 1 1 2 3 |                                             |
|     | 0 0 1 1 2 |                                             |
|     | 0 0 0 1 3 |                                             |
|     | 0 0 0 0 1 |                                             |
|                                                               |
|              5       5                                        |
|o6 : Matrix ZZ  <-- ZZ                                         |
+---------------------------------------------------------------+

A useful boundary identity: for any partition \mu of n, the Kostka number with
\lambda = (n) is 1, counting the unique row tableau:

+-------------------------------------------+
|i7 : for mu in P list kostkaNumber({4}, mu)|
|                                           |
|o7 = {1, 1, 1, 1, 1}                       |
|                                           |
|o7 : List                                  |
+-------------------------------------------+

Similarly, the Kostka number K_{\lambda,(1^n)} counts standard Young tableaux
of shape \lambda, which for \lambda = (2,2) is 2 (the hook-length value),
matching the dimension of the corresponding irreducible S_4-representation:

+-------------------------------------+
|i8 : kostkaNumber({2,2}, {1,1,1,1})  |
|                                     |
|o8 = 2                               |
+-------------------------------------+
|i9 : kostkaNumber({2,1,1}, {1,1,1,1})|
|                                     |
|o9 = 3                               |
+-------------------------------------+

See also
========

  * toM -- Monomial (m-) basis representation
  * toS -- Schur (s-) basis representation
  * Basis -- Specifies the basis to use for a Schur ring

Ways to use kostkaNumber:
=========================

  * "kostkaNumber(BasicList,BasicList)"

For the programmer
==================

The object kostkaNumber, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8086:0.

Memoize -- Option to record values of the jacobiTrudi function
**************************************************************

Description
===========

This is an optional argument for the jacobiTrudi, function,
allowing one to store its values in order to speed up computations.  When
Memoize => true, every computed value is cached in a hash table on the
symmetric ring, so repeated calls on the same partition return the cached value
in constant time.

+------------------------------------------------------------+
|i1 : R = symmetricRing(QQ, 10);                             |
+------------------------------------------------------------+
|i2 : elapsedTime jacobiTrudi({4,3,2,1}, R, Memoize => true);|
| -- .000882548s elapsed                                     |
+------------------------------------------------------------+
|i3 : elapsedTime jacobiTrudi({4,3,2,1}, R, Memoize => true);|
| -- .000043586s elapsed                                     |
+------------------------------------------------------------+

The cache is attached to the ring R.  After one partition is memoized,
subsequent calls with a different partition perform the full Jacobi-Trudi
determinant expansion, then cache it as well:

+----------------------------------------------------------+
|i4 : elapsedTime jacobiTrudi({5,3,2}, R, Memoize => true);|
| -- .000733044s elapsed                                   |
+----------------------------------------------------------+
|i5 : elapsedTime jacobiTrudi({5,3,2}, R, Memoize => true);|
| -- .000014402s elapsed                                   |
+----------------------------------------------------------+

Without Memoize => true, each call recomputes the determinant from scratch; for
large partitions this can be substantially more expensive than a single cached
lookup.

+-------------------------------------------+
|i6 : elapsedTime jacobiTrudi({4,3,2,1}, R);|
| -- .000011778s elapsed                    |
+-------------------------------------------+
|i7 : elapsedTime jacobiTrudi({4,3,2,1}, R);|
| -- .000012429s elapsed                    |
+-------------------------------------------+

See also
========

  * jacobiTrudi -- Jacobi-Trudi determinant

Functions with optional argument named Memoize:
===============================================

  * jacobiTrudi(...,Memoize=>...)
    -- Store values of the
    jacobiTrudi function.

For the programmer
==================

The object Memoize, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7709:0.

modificationRule -- Apply the Sam-Snowden-Weyman modification rule
******************************************************************

  * Usage:
        result = modificationRule(lambda, n, type)
  * Inputs:
      * lambda, a basic list (Macaulay2Doc), a partition
      * n, an integer (Macaulay2Doc), the target rank
      * type, a string (Macaulay2Doc), one of "C", "B", or "D" --
        see below
  * Outputs:
      * result, a sequence (Macaulay2Doc), either a pair (tau,
        sign) giving the modified partition $\tau$ and a sign $\pm 1$, or
        null (Macaulay2Doc), if $\lambda$ reduces to zero under the rule

Description
===========

This is the underlying combinatorial primitive used by specialize,
and by the finite-rank multiplication in Sp and O character rings.
It implements the modification rules of Sam, Snowden, and Weyman, which
describe how a universal classical group character becomes a character of the
finite-rank group (or vanishes).

The type argument selects the classical family:

$\bullet$ "C": symplectic groups Sp(2n).

$\bullet$ "B": odd orthogonal groups O(2n+1).

$\bullet$ "D": even orthogonal groups O(2n).

Given a partition lambda, the rule either returns a pair (tau, sign), meaning
that the universal character indexed by lambda equals sign times the
finite-rank character indexed by tau, or returns null, meaning the finite-rank
character vanishes.

+--------------------------------------+
|i1 : modificationRule({2,1,1}, 1, "C")|
|                                      |
|o1 = ({2}, -1)                        |
|                                      |
|o1 : Sequence                         |
+--------------------------------------+
|i2 : modificationRule({2,1,1}, 2, "C")|
+--------------------------------------+
|i3 : modificationRule({3,1,1}, 1, "B")|
+--------------------------------------+
|i4 : modificationRule({2,2}, 1, "D")  |
|                                      |
|o4 = ({2}, -1)                        |
|                                      |
|o4 : Sequence                         |
+--------------------------------------+

A partition can become ``stuck in the bulk'' after modification: the rule
reduces a long partition to a shorter (but still nonempty) partition, possibly
with a sign.  For example $\lambda = (4,4,2,1)$ at rank 2 in type $B$ reduces
to $\tau = (4,4,1)$ with sign $-1$:

+----------------------------------------+
|i5 : modificationRule({4,4,2,1}, 2, "B")|
|                                        |
|o5 = ({4, 4, 1}, -1)                    |
|                                        |
|o5 : Sequence                           |
+----------------------------------------+

Other partitions cancel to null: the rule applies and the finite-rank character
vanishes outright.  For instance, in type $C$ the partition $(3,2,2,2,1)$ at
rank 2 is killed, and so is $(4,3,2,1)$ at rank 2:

+------------------------------------------+
|i6 : modificationRule({3,2,2,2,1}, 2, "C")|
+------------------------------------------+
|i7 : modificationRule({4,3,2,1}, 2, "C")  |
+------------------------------------------+

Type $B$ and type $D$ give different answers on the same partition even at the
same rank.  For $\lambda = (3,2,1)$ at rank 2, type $B$ keeps the partition
unchanged (with sign $+1$) while type $D$ kills it:

+--------------------------------------+
|i8 : modificationRule({3,2,1}, 2, "B")|
|                                      |
|o8 = ({3, 2, 1}, 1)                   |
|                                      |
|o8 : Sequence                         |
+--------------------------------------+
|i9 : modificationRule({3,2,1}, 2, "D")|
+--------------------------------------+

Conversely, $\lambda = (4,3,2)$ at rank 2 is killed by type $B$ but survives
(with a sign) in type $D$:

+---------------------------------------+
|i10 : modificationRule({4,3,2}, 2, "B")|
+---------------------------------------+
|i11 : modificationRule({4,3,2}, 2, "D")|
|                                       |
|o11 = ({4, 3}, -1)                     |
|                                       |
|o11 : Sequence                         |
+---------------------------------------+

Most users will not call modificationRule directly; it is invoked automatically
by the finite-rank multiplication and by specialize.  It is
exported so that library code that wishes to implement custom variants (e.g.
twisted character rings, or non-standard specialization schemes) can share the
same combinatorics.

See also
========

  * specialize -- Specialize a stable character to a finite
    rank
  * toSp -- Expansion in the basis of symplectic characters
  * toO -- Expansion in the basis of orthogonal characters
  * GroupActing -- Specifies the group that is acting
  * OddOrEven -- Select type $B_n$ or type $D_n$ for an
    orthogonal Schur ring

For the programmer
==================

The object modificationRule, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:9292:0.

numgens(SchurRing) -- Number of generators of Schur ring.
*********************************************************

  * Function: numgens (Macaulay2Doc),

Description
===========

Given a Schur ring S, the function numgens outputs the number of generators of
S. This is equal to the relative dimension of S over its base ring, and also to
the maximal number of parts of a partition allowed as an index for the elements
of S.

+---------------------------+
|i1 : R = schurRing(QQ,r,6);|
+---------------------------+
|i2 : numgens R             |
|                           |
|o2 = 6                     |
+---------------------------+
|i3 : S = schurRing(s);     |
+---------------------------+
|i4 : numgens S             |
|                           |
|o4 = infinity              |
|                           |
|o4 : InfiniteNumber        |
+---------------------------+

When a Schur ring is built on top of another Schur ring as its coefficient
ring, numgens measures only the outermost (relative) layer.  Nested Schur rings
thus model tensor products of representation rings, each layer tracked by its
own numgens (Macaulay2Doc).

+------------------------------+
|i5 : A = schurRing(QQ,a,3);   |
+------------------------------+
|i6 : B = schurRing(A,b,2);    |
+------------------------------+
|i7 : numgens B                |
|                              |
|o7 = 2                        |
+------------------------------+
|i8 : numgens coefficientRing B|
|                              |
|o8 = 3                        |
+------------------------------+

The numgens value for a stable Schur ring (built with n => infinity or without
an explicit rank) is infinity (Macaulay2Doc), reflecting the
fact that no partition length is excluded.

+----------------------------+
|i9 : Sinf = schurRing(QQ,u);|
+----------------------------+
|i10 : numgens Sinf          |
|                            |
|o10 = infinity              |
|                            |
|o10 : InfiniteNumber        |
+----------------------------+
|i11 : u_{4,3,2,1}           |
|                            |
|o11 = u                     |
|       4,3,2,1              |
|                            |
|o11 : Sinf                  |
+----------------------------+

The same rule applies to the symplectic and orthogonal flavors.

+------------------------------------------------------------------+
|i12 : Sp = schurRing(QQ,sp,4,GroupActing => "Sp");                |
+------------------------------------------------------------------+
|i13 : numgens Sp                                                  |
|                                                                  |
|o13 = 4                                                           |
+------------------------------------------------------------------+
|i14 : O = schurRing(QQ,o,5,GroupActing => "O",OddOrEven => "Odd");|
+------------------------------------------------------------------+
|i15 : numgens O                                                   |
|                                                                  |
|o15 = 5                                                           |
+------------------------------------------------------------------+

See also
========

  * schurRing -- Make a SchurRing
  * SchurRing -- The class of all Schur rings

Ways to use this method:
========================

  * numgens(SchurRing) -- Number of generators
    of Schur ring.
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5514:0.

OddOrEven -- Select type $B_n$ or type $D_n$ for an orthogonal Schur ring
*************************************************************************

Description
===========

This is an optional argument for the schurRing, constructor
(and, by extension, the symmetricRing, and
specialize, methods), relevant only when GroupActing => "O".  It
distinguishes the two flavors of orthogonal group: odd (O(2n+1), type $B_n$)
and even (O(2n), type $D_n$). Its possible values are "Odd" (the default) and
"Even"; any other value raises an error.

For stable orthogonal rings (rank infinity) the distinction is invisible at the
level of multiplication, but it affects the dimension formula and the
modification rule applied when specialize, is called.

+------------------------------------------------------------------------+
|i1 : OB = schurRing(QQ, oB, 2, GroupActing => "O", OddOrEven => "Odd"); |
+------------------------------------------------------------------------+
|i2 : OD = schurRing(QQ, oD, 2, GroupActing => "O", OddOrEven => "Even");|
+------------------------------------------------------------------------+
|i3 : dim oB_{1}                                                         |
|                                                                        |
|o3 = 5                                                                  |
+------------------------------------------------------------------------+
|i4 : dim oD_{1}                                                         |
|                                                                        |
|o4 = 4                                                                  |
+------------------------------------------------------------------------+

At rank 3 and $\lambda = (2,1)$, the difference is much more pronounced: O(7)
(type $B_3$) gives a 105-dimensional irreducible, whereas O(6) (type $D_3$)
gives a 64-dimensional one:

+---------------------------------------------------------------------------+
|i5 : Oodd  = schurRing(QQ, od, 3, GroupActing => "O", OddOrEven => "Odd"); |
+---------------------------------------------------------------------------+
|i6 : Oeven = schurRing(QQ, oe, 3, GroupActing => "O", OddOrEven => "Even");|
+---------------------------------------------------------------------------+
|i7 : dim od_{2,1}                                                          |
|                                                                           |
|o7 = 105                                                                   |
+---------------------------------------------------------------------------+
|i8 : dim oe_{2,1}                                                          |
|                                                                           |
|o8 = 64                                                                    |
+---------------------------------------------------------------------------+

The same partition of larger weight separates the two flavors by an even bigger
factor.  For $\lambda = (3,2)$ the $O(7)$ Weyl dimension is 693 while the
$O(6)$ Weyl dimension is 300:

+------------------+
|i9 : dim od_{3,2} |
|                  |
|o9 = 693          |
+------------------+
|i10 : dim oe_{3,2}|
|                  |
|o10 = 300         |
+------------------+

Supplying OddOrEven for a non-orthogonal ring (for example GroupActing => "Sp"
or "GL") is an error.

+-----------------------------------------------------------------------------+
|i11 : try (schurRing(QQ, bad, 2, GroupActing => "GL", OddOrEven => "Odd"))   |
|schurRing rejected OddOrEven on a non-O ring                                 |
|-----------------------------------------------------------------------------|
|else print "schurRing rejected OddOrEven on a non-O ring"                    |
+-----------------------------------------------------------------------------+

See also
========

  * GroupActing -- Specifies the group that is acting
  * schurRing -- Make a SchurRing
  * specialize -- Specialize a stable character to a finite
    rank
  * toO -- Expansion in the basis of orthogonal characters
  * dim (Macaulay2Doc) -- compute the Krull dimension

Functions with optional argument named OddOrEven:
=================================================

  * "schurRing(...,OddOrEven=>...)"
  * "specialize(...,OddOrEven=>...)"
  * "symmetricRing(...,OddOrEven=>...)"

For the programmer
==================

The object OddOrEven, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:9184:0.

partitions(Set,BasicList) -- Partitions of a set
************************************************

  * Function: partitions (Macaulay2Doc),
  * Usage:
        par = partitions(S,L)
  * Inputs:
      * S, a set (Macaulay2Doc),
      * L, a basic list (Macaulay2Doc), a nonincreasing list
        of integers, or a partition
  * Outputs:
      * par, a list (Macaulay2Doc),

Description
===========

Given a set S and a partition L=\{l_1\geq l_2\geq\cdots\}, the method returns
the list of set-partitions of S of type L, i.e. ways of writing S=S_1\cup
S_2\cup\cdots with the S_i pairwise disjoint and |S_i|=l_i.  The blocks come
out as an unordered collection of sets.

+-----------------------------------------------------------------------------+
|i1 : partitions(set{1,2,3,4},{2,1,1})                                        |
|                                                                             |
|o1 = {set {set {3}, set {4}, set {1, 2}}, set {set {1, 3}, set {4}, set {2}},|
|     ------------------------------------------------------------------------|
|     set {set {3}, set {2}, set {4, 1}}, set {set {1}, set {4}, set {2, 3}}, |
|     ------------------------------------------------------------------------|
|     set {set {4, 2}, set {3}, set {1}}, set {set {1}, set {2}, set {4, 3}}} |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : partitions(set{a,b,c,d,e},new Partition from {3,2})                     |
|                                                                             |
|o2 = {set {set {c, d, e}, set {a, b}}, set {set {c, d, a}, set {e, b}}, set  |
|     ------------------------------------------------------------------------|
|     {set {a, e}, set {c, d, b}}, set {set {c, a, e}, set {d, b}}, set {set  |
|     ------------------------------------------------------------------------|
|     {c, e, b}, set {d, a}}, set {set {c, a, b}, set {d, e}}, set {set {d, a,|
|     ------------------------------------------------------------------------|
|     e}, set {c, b}}, set {set {c, a}, set {d, e, b}}, set {set {c, e}, set  |
|     ------------------------------------------------------------------------|
|     {d, a, b}}, set {set {a, e, b}, set {c, d}}}                            |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+

Changing the shape L changes the cycle type.  Two blocks of size 2 and one
fixed point on five points is the number of permutations of cycle type (2,2,1)
divided by the size of the corresponding centralizer:

+-----------------------------------------------------------------------------+
|i3 : partitions(set{1,2,3,4,5},{2,2,1})                                      |
|                                                                             |
|o3 = {set {set {5}, set {4, 3}, set {1, 2}}, set {set {5, 3}, set {4}, set   |
|     ------------------------------------------------------------------------|
|     {1, 2}}, set {set {3}, set {4, 5}, set {1, 2}}, set {set {4, 2}, set    |
|     ------------------------------------------------------------------------|
|     {5}, set {1, 3}}, set {set {1, 3}, set {4}, set {5, 2}}, set {set {5},  |
|     ------------------------------------------------------------------------|
|     set {2, 3}, set {4, 1}}, set {set {5, 1}, set {4}, set {2, 3}}, set {set|
|     ------------------------------------------------------------------------|
|     {3}, set {5, 2}, set {4, 1}}, set {set {4, 2}, set {3}, set {5, 1}}, set|
|     ------------------------------------------------------------------------|
|     {set {1, 3}, set {2}, set {4, 5}}, set {set {5, 3}, set {2}, set {4,    |
|     ------------------------------------------------------------------------|
|     1}}, set {set {5, 1}, set {2}, set {4, 3}}, set {set {1}, set {4, 5},   |
|     ------------------------------------------------------------------------|
|     set {2, 3}}, set {set {4, 2}, set {1}, set {5, 3}}, set {set {1}, set   |
|     ------------------------------------------------------------------------|
|     {4, 3}, set {5, 2}}}                                                    |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : #partitions(set{1,2,3,4,5},{2,2,1})                                     |
|                                                                             |
|o4 = 15                                                                      |
+-----------------------------------------------------------------------------+

Passing a Partition (Macaulay2Doc), is equivalent to passing
the underlying list; counting block-partitions of shape (3,1) recovers 4
\choose 1:

+-----------------------------------------------------------------------------+
|i5 : partitions(set{1,2,3,4},new Partition from {3,1})                       |
|                                                                             |
|o5 = {set {set {4}, set {1, 2, 3}}, set {set {4, 1, 2}, set {3}}, set {set   |
|     ------------------------------------------------------------------------|
|     {2}, set {4, 1, 3}}, set {set {4, 2, 3}, set {1}}}                      |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : #partitions(set{1,2,3,4},new Partition from {3,1})                      |
|                                                                             |
|o6 = 4                                                                       |
+-----------------------------------------------------------------------------+

Supplying a single-block shape returns a singleton list: the only set-partition
of type (n) is S itself.

+-------------------------------+
|i7 : partitions(set{1,2,3},{3})|
|                               |
|o7 = {set {set {1, 2, 3}}}     |
|                               |
|o7 : List                      |
+-------------------------------+

Ways to use this method:
========================

  * partitions(Set,BasicList), --
    Partitions of a set
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6764:0.

plethysm -- Plethystic operations on representations
****************************************************

  * Usage:
        pl = plethysm(f,g)
        pl = f @ g
  * Inputs:
      * f, a ring element (Macaulay2Doc), element of
        Symmetric ring or Schur ring
      * g, a ring element (Macaulay2Doc), element of
        Symmetric ring or Schur ring
  * Outputs:
      * pl, a ring element (Macaulay2Doc), element of the
        ring of g

Description
===========

Given a symmetric function f and the character g of a virtual representation of
a product of general linear and symmetric groups, the method computes the
character of the plethystic composition of f and g. The result of this
operation will be an element of the ring of g. We use the binary operator
@ (Macaulay2Doc), as a synonym for the plethysm function.

+----------------------------------------------------------------------------+
|i1 : R = symmetricRing(QQ,5);                                               |
+----------------------------------------------------------------------------+
|i2 : pl = plethysm(h_2,h_3)                                                 |
|                                                                            |
|      6     4       2 2     3     3                2     2                  |
|o2 = e  - 5e e  + 7e e  - 2e  + 3e e  - 6e e e  + e  - 2e e  + 3e e  + e e  |
|      1     1 2     1 2     2     1 3     1 2 3    3     1 4     2 4    1 5 |
|                                                                            |
|o2 : R                                                                      |
+----------------------------------------------------------------------------+
|i3 : toS pl                                                                 |
|                                                                            |
|o3 = s  + s                                                                 |
|      6    4,2                                                              |
|                                                                            |
|o3 : schurRing (QQ, s, 5)                                                   |
+----------------------------------------------------------------------------+
|i4 : S = schurRing(QQ,q,3);                                                 |
+----------------------------------------------------------------------------+
|i5 : h_2 @ q_{2,1}                                                          |
|                                                                            |
|o5 = q    + q      + q                                                      |
|      4,2    3,2,1    2,2,2                                                 |
|                                                                            |
|o5 : S                                                                      |
+----------------------------------------------------------------------------+
|i6 : plethysm(q_{2,1},q_{2,1})                                              |
|                                                                            |
|o6 = q      + q    + 2q      + q      + q      + 3q                         |
|      6,2,1    5,4     5,3,1    5,2,2    4,4,1     4,3,2                    |
|                                                                            |
|o6 : S                                                                      |
+----------------------------------------------------------------------------+
|i7 : T = schurRing(S,t,2,GroupActing => "Sn");                              |
+----------------------------------------------------------------------------+
|i8 : plethysm(q_{1,1,1}-q_{2,1}+q_{3},q_{2,1}*t_2-t_{1,1})                  |
|                                                                            |
|o8 = (q    - q      - q    + q      + q      - q      + 2q     )t  - q  t   |
|       6,3    6,2,1    5,4    5,2,2    4,4,1    4,3,2     3,3,3  2    () 1,1|
|                                                                            |
|o8 : T                                                                      |
+----------------------------------------------------------------------------+
|i9 : p_3 @ (q_{2,1}*t_2-t_{1,1})                                            |
|                                                                            |
|o9 = (q    - q      - q    + q      + q      - q      + 2q     )t  - q  t   |
|       6,3    6,2,1    5,4    5,2,2    4,4,1    4,3,2     3,3,3  2    () 1,1|
|                                                                            |
|o9 : T                                                                      |
+----------------------------------------------------------------------------+

Since the power-sum basis behaves multiplicatively under plethysm, one has the
identity plethysm(p_m, p_n) = p_{mn}, and more generally any complete/power-sum
pair commutes under plethysm, as shown below:

+----------------------------------------------------+
|i10 : R = symmetricRing(QQ,8);                      |
+----------------------------------------------------+
|i11 : toS plethysm(p_2,p_3) == toS p_6              |
|                                                    |
|o11 = true                                          |
+----------------------------------------------------+
|i12 : toS plethysm(h_3,p_2) == toS plethysm(p_2,h_3)|
|                                                    |
|o12 = true                                          |
+----------------------------------------------------+

The symmetric and antisymmetric squares of an irreducible representation
decompose via Sym^2 = plethysm(\{2\},-) and \Lambda^2 = plethysm(\{1,1\},-),
and their sum recovers the ordinary tensor square:

+---------------------------------------+
|i13 : S = schurRing(QQ,s,4);           |
+---------------------------------------+
|i14 : sym2 = plethysm({2},s_{2,1})     |
|                                       |
|o14 = s    + s      + s        + s     |
|       4,2    3,2,1    3,1,1,1    2,2,2|
|                                       |
|o14 : S                                |
+---------------------------------------+
|i15 : wedge2 = plethysm({1,1},s_{2,1}) |
|                                       |
|o15 = s      + s    + s      + s       |
|       4,1,1    3,3    3,2,1    2,2,1,1|
|                                       |
|o15 : S                                |
+---------------------------------------+
|i16 : s_{2,1}*s_{2,1} - sym2 - wedge2  |
|                                       |
|o16 = 0                                |
|                                       |
|o16 : S                                |
+---------------------------------------+

Plethysm makes sense for representations of symmetric groups as well.  In an
Sn-flavored ring, plethysm(lambda, chi) applies the Schur functor S_lambda to
the Sn-representation chi:

+-------------------------------------------------+
|i17 : Sn = schurRing(QQ,c,4,GroupActing => "Sn");|
+-------------------------------------------------+
|i18 : plethysm({2,1},c_{2,1,1})                  |
|                                                 |
|o18 = c    + c    + c                            |
|       3,1    2,2    2,1,1                       |
|                                                 |
|o18 : Sn                                         |
+-------------------------------------------------+

Plethysm also works over tensor products of Schur rings, mixing a GL factor and
an Sn factor:

+-----------------------------------------------+
|i19 : G = schurRing(QQ,g,3);                   |
+-----------------------------------------------+
|i20 : N = schurRing(G,n,3,GroupActing => "Sn");|
+-----------------------------------------------+
|i21 : plethysm({2},g_1*n_{2,1})                |
|                                               |
|o21 = g n  + g n    + g   n                    |
|       2 3    2 2,1    1,1 1,1,1               |
|                                               |
|o21 : N                                        |
+-----------------------------------------------+

Ways to use plethysm:
=====================

  * "plethysm(RingElement,RingElement)"
  * plethysm(BasicList,RingElement)
    -- Plethystic operations on
    representations
  * "plethysm(BasicList,ClassFunction)" -- see
    plethysm(RingElement,ClassFunction),
    -- Plethystic operations on
    class functions
  * plethysm(RingElement,ClassFunction)
    -- Plethystic operations on
    class functions

For the programmer
==================

The object plethysm, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6262:0.

plethysm(BasicList,RingElement) -- Plethystic operations on representations
***************************************************************************

  * Function: plethysm,
  * Usage:
        pl = plethysm(lambda,g)
  * Inputs:
      * lambda, a basic list (Macaulay2Doc), nonincreasing
        sequence of positive integers, or partition
      * g, a ring element (Macaulay2Doc), element of
        Symmetric ring or Schur ring
  * Outputs:
      * pl, a ring element (Macaulay2Doc), element of the
        ring of g

Description
===========

The method computes the character of the representation obtained by applying
the Schur functor S_{\lambda} to the representation with character g, where
\lambda is a partition.

+----------------------------------------------------------+
|i1 : R = symmetricRing(QQ,3);                             |
+----------------------------------------------------------+
|i2 : S = schurRing(QQ,q,3);                               |
+----------------------------------------------------------+
|i3 : toE plethysm({2,1},e_1*e_2-e_3)                      |
|                                                          |
|        4    4         2 2      3      3 2         2     3|
|o3 = e e  + e e e  - 4e e e  - e e  - e e  + 7e e e  - 3e |
|      1 2    1 2 3     1 2 3    2 3    1 3     1 2 3     3|
|                                                          |
|o3 : R                                                    |
+----------------------------------------------------------+
|i4 : plethysm({2,1,1},q_{1,1})                            |
|                                                          |
|o4 = q                                                    |
|      3,3,2                                               |
|                                                          |
|o4 : S                                                    |
+----------------------------------------------------------+
|i5 : T = schurRing(S,t,4,GroupActing => "Sn");            |
+----------------------------------------------------------+
|i6 : plethysm({1,1},q_1*t_{3,1})                          |
|                                                          |
|o6 = q   t  + q   t    + q   t    + q t                   |
|      1,1 4    1,1 3,1    1,1 2,2    2 2,1,1              |
|                                                          |
|o6 : T                                                    |
+----------------------------------------------------------+

Even simple plethysms of Schur functions are not obvious a priori. For example,
Sym^2 of the antisymmetric square $\Lambda^2 V = S_{1,1}V$ breaks up as:

+---------------------------+
|i7 : S = schurRing(QQ,s,4);|
+---------------------------+
|i8 : plethysm({2},s_{1,1}) |
|                           |
|o8 = s    + s              |
|      2,2    1,1,1,1       |
|                           |
|o8 : S                     |
+---------------------------+

Applying a partition directly lets one extract isotypic summands, e.g.\ the two
pieces of V^{\otimes 2} for an Sn-representation:

+------------------------------------------------+
|i9 : Sn = schurRing(QQ,c,4,GroupActing => "Sn");|
+------------------------------------------------+
|i10 : sym2chi = plethysm({2}, c_{3,1})          |
|                                                |
|o10 = c  + c    + c                             |
|       4    3,1    2,2                          |
|                                                |
|o10 : Sn                                        |
+------------------------------------------------+
|i11 : wed2chi = plethysm({1,1}, c_{3,1})        |
|                                                |
|o11 = c                                         |
|       2,1,1                                    |
|                                                |
|o11 : Sn                                        |
+------------------------------------------------+
|i12 : c_{3,1}*c_{3,1} - sym2chi - wed2chi       |
|                                                |
|o12 = 0                                         |
|                                                |
|o12 : Sn                                        |
+------------------------------------------------+

For representations of products of groups, the plethysm is applied diagonally;
here on a GL x GL tensor product:

+----------------------------+
|i13 : A = schurRing(QQ,a,3);|
+----------------------------+
|i14 : B = schurRing(A,b,2); |
+----------------------------+
|i15 : plethysm({2},a_1*b_1) |
|                            |
|o15 = a b  + a   b          |
|       2 2    1,1 1,1       |
|                            |
|o15 : B                     |
+----------------------------+

Ways to use this method:
========================

  * plethysm(BasicList,RingElement)
    -- Plethystic operations on
    representations
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6325:0.

plethysm(RingElement,ClassFunction) -- Plethystic operations on class functions
*******************************************************************************

  * Function: plethysm,
  * Usage:
        pl = plethysm(f,cF)
        pl = plethysm(lambda,cF)
  * Inputs:
      * a ring element (Macaulay2Doc),
      * a Class function,

Description
===========

These methods describe the result of applying plethystic operations to a
virtual character of a symmetric group. These operations are described either
via a symmetric function f, or a partition lambda. Since cF corresponds to an
S_n- representation, the option GroupActing, is irrelevant
in this case.

+---------------------------------------------------------+
|i1 : cF = new ClassFunction from {{2} => 1, {1,1} => -1};|
+---------------------------------------------------------+
|i2 : pl1 = plethysm({1,1},cF)                            |
|                                                         |
|o2 = ClassFunction{{1, 1} => 1}                          |
|                   {2} => 1                              |
|                                                         |
|o2 : ClassFunction                                       |
+---------------------------------------------------------+
|i3 : R = symmetricRing 5;                                |
+---------------------------------------------------------+
|i4 : pl2 = plethysm(e_1+e_2,cF)                          |
|                                                         |
|o4 = ClassFunction{{1, 1} => 0}                          |
|                   {2} => 2                              |
|                                                         |
|o4 : ClassFunction                                       |
+---------------------------------------------------------+
|i5 : S = schurRing R;                                    |
+---------------------------------------------------------+
|i6 : symmetricFunction(cF,S)                             |
|                                                         |
|o6 = -s                                                  |
|       1,1                                               |
|                                                         |
|o6 : S                                                   |
+---------------------------------------------------------+
|i7 : symmetricFunction(pl1,S)                            |
|                                                         |
|o7 = s                                                   |
|      2                                                  |
|                                                         |
|o7 : S                                                   |
+---------------------------------------------------------+
|i8 : symmetricFunction(pl2,S)                            |
|                                                         |
|o8 = s  - s                                              |
|      2    1,1                                           |
|                                                         |
|o8 : S                                                   |
+---------------------------------------------------------+

Applying the partition \{2\} to the sign character of S_2 gives Sym^2 of the
sign, which is the trivial representation of S_4:

+---------------------------------------------------------------------+
|i9 : sgn = new ClassFunction from {{2} => -1, {1,1} => 1};           |
+---------------------------------------------------------------------+
|i10 : pl = plethysm({2},sgn)                                         |
|                                                                     |
|o10 = ClassFunction{{1, 1} => 1}                                     |
|                    {2} => 1                                         |
|                                                                     |
|o10 : ClassFunction                                                  |
+---------------------------------------------------------------------+
|i11 : symmetricFunction(pl, schurRing(QQ, s, 4, GroupActing => "Sn"))|
|                                                                     |
|o11 = s                                                              |
|       2                                                             |
|                                                                     |
|o11 : schurRing (QQ, s, 4)                                           |
+---------------------------------------------------------------------+

Plethysm by a power-sum class function is Adams-type: p_k sends a
representation to its k-th Adams operation (on class functions).

+-------------------------------------------------------------------------+
|i12 : cF2 = new ClassFunction from {{3} => 2, {2,1} => 0, {1,1,1} => -1};|
+-------------------------------------------------------------------------+
|i13 : R2 = symmetricRing 4;                                              |
+-------------------------------------------------------------------------+
|i14 : plethysm(p_2, cF2)                                                 |
|                                                                         |
|o14 = ClassFunction{{1, 1, 1} => -1}                                     |
|                    {2, 1} => -1                                         |
|                    {3} => 2                                             |
|                                                                         |
|o14 : ClassFunction                                                      |
+-------------------------------------------------------------------------+

Ways to use this method:
========================

  * "plethysm(BasicList,ClassFunction)"
  * plethysm(RingElement,ClassFunction)
    -- Plethystic operations on
    class functions
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6375:0.

pVariable -- Power-sum symmetric functions in a Symmetric ring
**************************************************************

Description
===========

For a Symmetric ring R of dimension n, R.pVariable is a function which assigns
to each index 1\leq i\leq n the i-th power-sum symmetric function. If i is
outside the given bounds, an error is returned.

+-----------------------------+
|i1 : R = symmetricRing(QQ,4);|
+-----------------------------+
|i2 : R.pVariable 2           |
|                             |
|o2 = p                       |
|      2                      |
|                             |
|o2 : R                       |
+-----------------------------+

Power sums are an algebraically independent generating set for the ring of
symmetric functions over QQ (Macaulay2Doc), and products of p_i's
expand into the Schur basis using the character table of the symmetric group.

+-----------------------------------------------------------------------------+
|i3 : R = symmetricRing(QQ,5);                                                |
+-----------------------------------------------------------------------------+
|i4 : toS ((R.pVariable 2)^3)                                                 |
|                                                                             |
|o4 = s  - s    + 3s    - 2s      - 3s    + 2s        + 3s      - 3s        + |
|      6    5,1     4,2     4,1,1     3,3     3,1,1,1     2,2,2     2,2,1,1   |
|     ------------------------------------------------------------------------|
|     s                                                                       |
|      2,1,1,1,1                                                              |
|                                                                             |
|o4 : schurRing (QQ, s, 5)                                                    |
+-----------------------------------------------------------------------------+

The same variable in a Symmetric ring with GroupActing => "Sn" represents a
virtual character of a symmetric group, and conversion to elementary and
complete generators is handled by toE, and toH.

+---------------------------------------------------+
|i5 : Rsn = symmetricRing(QQ,4,GroupActing => "Sn");|
+---------------------------------------------------+
|i6 : toE (Rsn.pVariable 2)                         |
|                                                   |
|      2                                            |
|o6 = e  - 2e                                       |
|      1     2                                      |
|                                                   |
|o6 : Rsn                                           |
+---------------------------------------------------+
|i7 : toH (Rsn.pVariable 3)                         |
|                                                   |
|      3                                            |
|o7 = h  - 3h h  + 3h                               |
|      1     1 2     3                              |
|                                                   |
|o7 : Rsn                                           |
+---------------------------------------------------+

Power sums are also useful as the natural input to plethysm.

+-----------------------------------------------+
|i8 : R = symmetricRing(QQ,4);                  |
+-----------------------------------------------+
|i9 : toS plethysm(R.pVariable 2, R.hVariable 2)|
|                                               |
|o9 = s  - s    + s                             |
|      4    3,1    2,2                          |
|                                               |
|o9 : schurRing (QQ, s, 4)                      |
+-----------------------------------------------+

See also
========

  * eVariable -- Elementary symmetric functions in a
    Symmetric ring
  * hVariable -- Complete symmetric functions in a Symmetric
    ring
  * symmetricRing -- Make a Symmetric ring
  * toS -- Schur (s-) basis representation
  * plethysm -- Plethystic operations on representations

For the programmer
==================

The object pVariable, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5457:0.

scalarProduct -- Standard pairing on symmetric functions/class functions
************************************************************************

Description
===========

This method computes the standard Hall scalar product on the ring \Lambda of
symmetric functions. One way to define this product is by imposing that the
collection of Schur functions s_{\lambda} form an orthonormal basis.

Alternatively, by the correspondence between symmetric functions and virtual
characters of symmetric groups, this scalar product coincides with the standard
scalar product on class functions.

The number of standard tableaux of shape \{4,3,2,1\} is:

+--------------------------------------+
|i1 : R = symmetricRing(QQ,10);        |
+--------------------------------------+
|i2 : S = schurRing(QQ,s,10);          |
+--------------------------------------+
|i3 : scalarProduct(h_1^10,s_{4,3,2,1})|
|                                      |
|o3 = 768                              |
|                                      |
|o3 : QQ                               |
+--------------------------------------+

The Schur basis is orthonormal: <s_\lambda, s_\mu> equals 1 if \lambda = \mu
and 0 otherwise.

+----------------------------------------+
|i4 : T = schurRing(QQ,t,5);             |
+----------------------------------------+
|i5 : scalarProduct(t_{3,1,1}, t_{3,1,1})|
|                                        |
|o5 = 1                                  |
|                                        |
|o5 : QQ                                 |
+----------------------------------------+
|i6 : scalarProduct(t_{3,1,1}, t_{2,2,1})|
|                                        |
|o6 = 0                                  |
|                                        |
|o6 : QQ                                 |
+----------------------------------------+
|i7 : scalarProduct(t_{4,1}, t_{3,2})    |
|                                        |
|o7 = 0                                  |
|                                        |
|o7 : QQ                                 |
+----------------------------------------+

The power-sum basis is orthogonal with norms given by the centralizer sizes:
<p_\rho, p_\rho> = z_\rho.  Here we verify this for the three partitions of 3.

+-------------------------------------------------------------+
|i8 : U = symmetricRing(QQ,4);                                |
+-------------------------------------------------------------+
|i9 : scalarProduct(p_3, p_3) == centralizerSize{0,0,1}       |
|                                                             |
|o9 = true                                                    |
+-------------------------------------------------------------+
|i10 : scalarProduct(p_2*p_1, p_2*p_1) == centralizerSize{1,1}|
|                                                             |
|o10 = true                                                   |
+-------------------------------------------------------------+
|i11 : scalarProduct(p_1^3, p_1^3) == centralizerSize{3}      |
|                                                             |
|o11 = true                                                   |
+-------------------------------------------------------------+

By the Cauchy identity, <p_1^n, p_1^n> counts the elements of S_n, i.e.\ it
equals n!:

+---------------------------------+
|i12 : scalarProduct(p_1^4, p_1^4)|
|                                 |
|o12 = 24                         |
|                                 |
|o12 : QQ                         |
+---------------------------------+

See also
========

  * internalProduct -- Internal product of symmetric
    functions/class functions
  * centralizerSize -- Size of the centralizer of a
    permutation

Ways to use scalarProduct:
==========================

  * scalarProduct(ClassFunction,ClassFunction)
    -- Standard scalar
    product of class functions
  * scalarProduct(RingElement,RingElement)
    -- Standard scalar product of
    symmetric functions

For the programmer
==================

The object scalarProduct, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7338:0.

scalarProduct(ClassFunction,ClassFunction) -- Standard scalar product of class functions
****************************************************************************************

  * Function: scalarProduct,
  * Usage:
        sp = scalarProduct(ch1,ch2)
  * Inputs:
      * ch1, a Class function,
      * ch2, a Class function,
  * Outputs:
      * sp, a rational number (Macaulay2Doc),

Description
===========

Given virtual characters ch1 and ch2, the method computes the standard pairing
between ch1 and ch2.

+-----------------------------------------------------------------------------+
|i1 : ch1 = new ClassFunction from {{3,2} => 2, {2,2,1} => -2, {3,1,1} => 2,  |
|-----------------------------------------------------------------------------|
|{5} => 1};                                                                   |
+-----------------------------------------------------------------------------+
|i2 : ch2 = new ClassFunction from {{2,2,1} => -2, {5} => 1, {1,1,1,1,1} => 5,|
|-----------------------------------------------------------------------------|
|{3,2} => 3, {4,1} => -2};                                                    |
+-----------------------------------------------------------------------------+
|i3 : scalarProduct(ch1,ch2)                                                  |
|                                                                             |
|     17                                                                      |
|o3 = --                                                                      |
|     10                                                                      |
|                                                                             |
|o3 : QQ                                                                      |
+-----------------------------------------------------------------------------+

The irreducible characters of S_n indexed by distinct partitions are
orthonormal.  For partitions of 5, we can verify the full orthogonality
relations:

+-------------------------------------+
|i4 : S = schurRing(QQ,s,5);          |
+-------------------------------------+
|i5 : cF32 = classFunction s_{3,2};   |
+-------------------------------------+
|i6 : cF41 = classFunction s_{4,1};   |
+-------------------------------------+
|i7 : cF221 = classFunction s_{2,2,1};|
+-------------------------------------+
|i8 : scalarProduct(cF32, cF32)       |
|                                     |
|o8 = 1                               |
|                                     |
|o8 : QQ                              |
+-------------------------------------+
|i9 : scalarProduct(cF32, cF41)       |
|                                     |
|o9 = 0                               |
|                                     |
|o9 : QQ                              |
+-------------------------------------+
|i10 : scalarProduct(cF41, cF221)     |
|                                     |
|o10 = 0                              |
|                                     |
|o10 : QQ                             |
+-------------------------------------+

Decomposing an arbitrary virtual character into irreducibles by pairing with
each Schur class function recovers the multiplicities:

+-----------------------------------------------------------------------------+
|i11 : psi = cF32 + 2*cF41 - cF221;                                           |
+-----------------------------------------------------------------------------+
|i12 : {scalarProduct(psi, cF32), scalarProduct(psi, cF41), scalarProduct(psi,|
|                                                                             |
|o12 = {1, 2, -1}                                                             |
|                                                                             |
|o12 : List                                                                   |
|-----------------------------------------------------------------------------|
|cF221)}                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * classFunction -- Converts symmetric function to class
    function

Ways to use this method:
========================

  * scalarProduct(ClassFunction,ClassFunction)
    -- Standard scalar
    product of class functions
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7447:0.

scalarProduct(RingElement,RingElement) -- Standard scalar product of symmetric functions
****************************************************************************************

  * Function: scalarProduct,
  * Usage:
        sp = scalarProduct(f1,f2)
  * Inputs:
      * f1, a ring element (Macaulay2Doc), element of a
        Symmetric Ring
      * f2, a ring element (Macaulay2Doc), element of a
        Symmetric Ring
  * Outputs:
      * sp, a rational number (Macaulay2Doc),

Description
===========

Given symmetric functions f1 and f2, the method computes the standard Hall
pairing between f1 and f2.

+-------------------------------+
|i1 : R = symmetricRing(QQ,5);  |
+-------------------------------+
|i2 : S = schurRing R           |
|                               |
|o2 = S                         |
|                               |
|o2 : SchurRing                 |
+-------------------------------+
|i3 : scalarProduct(h_5,p_5)    |
|                               |
|o3 = 1                         |
|                               |
|o3 : QQ                        |
+-------------------------------+
|i4 : scalarProduct(S_{4,1},p_5)|
|                               |
|o4 = -1                        |
|                               |
|o4 : QQ                        |
+-------------------------------+

Indeed, the coefficients of s_5 and s_{4,1} in the s-basis expansion of p_5 are
as computed above:

+-----------------------------------------------+
|i5 : toS p_5                                   |
|                                               |
|o5 = s  - s    + s      - s        + s         |
|      5    4,1    3,1,1    2,1,1,1    1,1,1,1,1|
|                                               |
|o5 : S                                         |
+-----------------------------------------------+

The pairing <e_n, p_n> equals (-1)^{n-1}, reflecting the sign character of the
symmetric group:

+----------------------------+
|i6 : scalarProduct(e_2, p_2)|
|                            |
|o6 = -1                     |
|                            |
|o6 : QQ                     |
+----------------------------+
|i7 : scalarProduct(e_3, p_3)|
|                            |
|o7 = 1                      |
|                            |
|o7 : QQ                     |
+----------------------------+
|i8 : scalarProduct(e_4, p_4)|
|                            |
|o8 = -1                     |
|                            |
|o8 : QQ                     |
+----------------------------+

The pairing <s_\lambda, h_\mu> recovers the Kostka number K_{\lambda,\mu}, the
number of semistandard Young tableaux of shape \lambda and content \mu.  We
cross-check this against kostkaNumber,:

+------------------------------------------------------------------------+
|i9 : scalarProduct(S_{3,2}, h_2*h_2*h_1) == kostkaNumber({3,2}, {2,2,1})|
|                                                                        |
|o9 = true                                                               |
+------------------------------------------------------------------------+
|i10 : scalarProduct(S_{3,2}, h_1^5) == kostkaNumber({3,2}, {1,1,1,1,1}) |
|                                                                        |
|o10 = true                                                              |
+------------------------------------------------------------------------+
|i11 : scalarProduct(S_{4,1}, h_3*h_2) == kostkaNumber({4,1}, {3,2})     |
|                                                                        |
|o11 = true                                                              |
+------------------------------------------------------------------------+

See also
========

  * kostkaNumber -- Compute a Kostka number

Ways to use this method:
========================

  * scalarProduct(RingElement,RingElement)
    -- Standard scalar product of
    symmetric functions
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7397:0.

schurLevel -- Number of SchurRings the ring is a tensor product of.
*******************************************************************

  * Usage:
        lev = schurLevel(R)
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Outputs:
      * lev, an integer (Macaulay2Doc),

Description
===========

For the representation ring R of a product of lev general linear and/or
symmetric groups, the function returns lev.  If R is not a representation ring,
the function returns 0.

+---------------------------+
|i1 : R = schurRing(QQ,r,3);|
+---------------------------+
|i2 : S = schurRing(R,s,5); |
+---------------------------+
|i3 : T = schurRing(S,t,2); |
+---------------------------+
|i4 : schurLevel R          |
|                           |
|o4 = 1                     |
+---------------------------+
|i5 : schurLevel S          |
|                           |
|o5 = 2                     |
+---------------------------+
|i6 : schurLevel T          |
|                           |
|o6 = 3                     |
+---------------------------+
|i7 : schurLevel QQ         |
|                           |
|o7 = 0                     |
+---------------------------+

A three-level tower mixing GL-factors with an S_n-factor counts each layer,
regardless of which group is acting:

+-----------------------------------------------+
|i8 : A = schurRing(QQ,a,3);                    |
+-----------------------------------------------+
|i9 : B = schurRing(A,b,4);                     |
+-----------------------------------------------+
|i10 : C = schurRing(B,c,2,GroupActing => "Sn");|
+-----------------------------------------------+
|i11 : schurLevel C                             |
|                                               |
|o11 = 3                                        |
+-----------------------------------------------+

A Symmetric ring (produced by symmetricRing) sits over a
single tower slot and reports schurLevel equal to 1, while an ordinary
polynomial ring or the base field report 0:

+-------------------------------------+
|i12 : schurLevel(symmetricRing(QQ,5))|
|                                     |
|o12 = 1                              |
+-------------------------------------+
|i13 : schurLevel(QQ[x,y,z])          |
|                                     |
|o13 = 0                              |
+-------------------------------------+
|i14 : schurLevel ZZ                  |
|                                     |
|o14 = 0                              |
+-------------------------------------+

Ways to use schurLevel:
=======================

  * "schurLevel(Ring)"

For the programmer
==================

The object schurLevel, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6708:0.

schurResolution -- Compute an ``approximate'' equivariant resolution of a module.
*********************************************************************************

  * Usage:
        resol = schurResolution(rep,M,lS)
        resol = schurResolution(rep,M)
  * Inputs:
      * rep, a ring element (Macaulay2Doc), element of a
        SchurRing
      * M, a list (Macaulay2Doc), list of representations,
        corresponding to the homogeneous components of a module M.
      * lS, a list (Macaulay2Doc), list of representations,
        corresponding to the homogeneous components of a polynomial ring S.
  * Optional inputs (Macaulay2Doc),:
      * DegreeLimit,
        => ..., default value 0, Specifies the maximal degree of syzygies
        to be computed
      * SyzygyLimit,
        => ..., default value 0, Specifies the number of syzygy modules to
        be computed
  * Outputs:
      * resol, a list (Macaulay2Doc),

Description
===========

Given a representation rep of a (product of) general linear or symmetric
group(s) G, we consider the symmetric algebra S = Sym(rep) and an S-module M
which is also a G-module in such a way that the S-module structure on M
respects the G-action. More generally, S can be any graded ring, of which one
inputs only finitely many homogeneous components as a list lS of characters of
G. The main reason why we allow this generality is because most of the time it
is computationally expensive to calculate the symmetric powers of the
representation rep, so we give the user the option to compute these symmetric
powers by different methods and use the results as input for the
schurResolution routine.

We are interested in computing an equivariant resolution of M. This depends on
both the G- and S-module structure of M in general, but in many examples that
occur in practice, it turns out that the differentials in the resolution have
maximal rank among all G-module homomorphisms between the free modules in the
resolution. We will therefore assume that this is the case for the module M
that we are trying to resolve, and thus disregard its S-module structure.

More precisely, the assumptions that we make about M are as follows: M is a
graded S-module, with M_i = 0 for i<0, where the grading on S is standard,
given by setting the degrees of the elements of rep equal to 1. Since we
assumed that the G-structure of M determines the syzygies, all the relevant
information is concentrated in finitely many homogeneous components of M
(namely up to reg(M)+pd(M), the sum of the regularity and the projective
dimension of M). We will thus assume that M is given as a list of
G-representations, corresponding to (a subset of) the relevant homogeneous
components. The function schurResolution takes as inputs the representation
rep, the module M, and as optional arguments a DegreeLimit d, and a SyzygyLimit
c. The ring S itself can occur as input data, being described as a list of
G-representations, just like M. The routine outputs the generators of degree at
most d of the first c+1 syzygy modules (from 0 to c). They are listed as a
sequence of pairs, consisting of the degree of the generators of the syzygy
modules together with the characters of the G-representations they correspond
to. If the syzygy bound c is not given, then all syzygy modules are computed.
If the degree bound d is not given, then it is assumed to be equal to the
largest degree among the homogeneous components of M in the input, i.e. one
less than the length of the List (Macaulay2Doc), M.

The example below computes the resolution of the quadratic Veronese surface in
P^5.

+------------------------------------------------------------+
|i1 : S = schurRing(QQ,s,3)                                  |
|                                                            |
|o1 = S                                                      |
|                                                            |
|o1 : SchurRing                                              |
+------------------------------------------------------------+
|i2 : rep = s_{2}                                            |
|                                                            |
|o2 = s                                                      |
|      2                                                     |
|                                                            |
|o2 : S                                                      |
+------------------------------------------------------------+
|i3 : M = {1_S,s_{2},s_{4},s_{6},s_{8},s_{10},s_{12}}        |
|                                                            |
|o3 = {s  , s , s , s , s , s  , s  }                        |
|       ()   2   4   6   8   10   12                         |
|                                                            |
|o3 : List                                                   |
+------------------------------------------------------------+
|i4 : schurResolution(rep,M)                                 |
|                                                            |
|o4 = {{(0, s  )}, {(2, s   )}, {(3, s     )}, {(4, s     )}}|
|            ()          2,2          3,2,1          3,3,2   |
|                                                            |
|o4 : List                                                   |
+------------------------------------------------------------+

Next, we compute the syzygies of degree at most 7 in the resolution of the
cubic Veronese embedding of P^2.

+-----------------------------------------------------------------------------+
|i5 : rep = s_{3}                                                             |
|                                                                             |
|o5 = s                                                                       |
|      3                                                                      |
|                                                                             |
|o5 : S                                                                       |
+-----------------------------------------------------------------------------+
|i6 : M = {1_S,s_{3},s_{6},s_{9},s_{12},s_{15},s_{18},s_{21},s_{24},s_{27}}   |
|                                                                             |
|o6 = {s  , s , s , s , s  , s  , s  , s  , s  , s  }                         |
|       ()   3   6   9   12   15   18   21   24   27                          |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : d = 7                                                                   |
|                                                                             |
|o7 = 7                                                                       |
+-----------------------------------------------------------------------------+
|i8 : schurResolution(rep,M,DegreeLimit => d)                                 |
|                                                                             |
|o8 = {{(0, s  )}, {(2, s   )}, {(3, s      + s    + s      + s     )}, {(4,  |
|            ()          4,2          6,2,1    5,4    5,3,1    4,3,2          |
|     ------------------------------------------------------------------------|
|     s      + s      + s      + s      + s      + s      + s     )}, {(5,    |
|      7,4,1    7,3,2    6,5,1    6,4,2    6,3,3    5,5,2    5,4,3            |
|     ------------------------------------------------------------------------|
|     s      + s      + s      + s      + s      + s      + s     )}, {(6,    |
|      8,5,2    8,4,3    7,6,2    7,5,3    7,4,4    6,6,3    6,5,4            |
|     ------------------------------------------------------------------------|
|     s      + s      + s      + s     )}, {(7, s     )}}                     |
|      9,5,4    8,7,3    8,6,4    7,6,5          9,7,5                        |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

We can compute the resolution of the ideal of 2\times 2 minors of a 3\times 4
matrix, which corresponds to the Segre embedding of P^2\times P^3:

+-----------------------------------------------------------------------------+
|i9 : T = schurRing(S,t,4)                                                    |
|                                                                             |
|o9 = T                                                                       |
|                                                                             |
|o9 : SchurRing                                                               |
+-----------------------------------------------------------------------------+
|i10 : rep = s_1 * t_1                                                        |
|                                                                             |
|o10 = s t                                                                    |
|       1 1                                                                   |
|                                                                             |
|o10 : T                                                                      |
+-----------------------------------------------------------------------------+
|i11 : M = {1_T} | apply(splice{1..8},i -> s_i * t_i)                         |
|                                                                             |
|o11 = {t  , s t , s t , s t , s t , s t , s t , s t , s t }                  |
|        ()   1 1   2 2   3 3   4 4   5 5   6 6   7 7   8 8                   |
|                                                                             |
|o11 : List                                                                   |
+-----------------------------------------------------------------------------+
|i12 : schurResolution(rep,M)                                                 |
|                                                                             |
|o12 = {{(0, t  )}, {(2, s   t   )}, {(3, s     t    + s   t     )}, {(4,     |
|             ()          1,1 1,1          1,1,1 2,1    2,1 1,1,1             |
|      -----------------------------------------------------------------------|
|      s     t      + s   t       )}, {(5, s     t       ), (6,               |
|       2,1,1 2,1,1    3,1 1,1,1,1          3,1,1 2,1,1,1                     |
|      -----------------------------------------------------------------------|
|      s     t     )}, {(7, s     t       )}, {(8, s     t       )}}          |
|       2,2,2 2,2,2          3,2,2 2,2,2,1          3,3,2 2,2,2,2             |
|                                                                             |
|o12 : List                                                                   |
+-----------------------------------------------------------------------------+

The following example computes the equivariant resolution of the residue field
of a polynomial ring in n=5 variables, with respect to the action of the
symmetric group S_n.

+-----------------------------------------------------------------------------+
|i13 : n = 5;                                                                 |
+-----------------------------------------------------------------------------+
|i14 : S = schurRing(QQ,s,n,GroupActing => "Sn");                             |
+-----------------------------------------------------------------------------+
|i15 : rep = s_n + s_{n-1,1};                                                 |
+-----------------------------------------------------------------------------+
|i16 : M = {s_n}                                                              |
|                                                                             |
|o16 = {s }                                                                   |
|        5                                                                    |
|                                                                             |
|o16 : List                                                                   |
+-----------------------------------------------------------------------------+
|i17 : schurResolution(rep,M,DegreeLimit => n)                                |
|                                                                             |
|o17 = {{(0, s )}, {(1, s  + s   )}, {(2, s    + s     )}, {(3, s      +      |
|             5          5    4,1          4,1    3,1,1          3,1,1        |
|      -----------------------------------------------------------------------|
|      s       )}, {(4, s        + s         )}, {(5, s         )}}           |
|       2,1,1,1          2,1,1,1    1,1,1,1,1          1,1,1,1,1              |
|                                                                             |
|o17 : List                                                                   |
+-----------------------------------------------------------------------------+

Generalizing this, we can compute the equivariant resolution of the quotient of
the polynomial ring in n=5 variables by the ideal of square-free monomials of
degree two, with respect to the action of the symmetric group S_n.

+-----------------------------------------------------------------------------+
|i18 : M = {s_n} | splice{n:rep};                                             |
+-----------------------------------------------------------------------------+
|i19 : schurResolution(rep,M)                                                 |
|                                                                             |
|o19 = {{(0, s )}, {(2, s  + s    + s   )}, {(3, s    + s    + s      +       |
|             5          5    4,1    3,2          4,1    3,2    3,1,1         |
|      -----------------------------------------------------------------------|
|      s     )}, {(4, s      + s      + s       )}, {(5, s       )}}          |
|       2,2,1          3,1,1    2,2,1    2,1,1,1          2,1,1,1             |
|                                                                             |
|o19 : List                                                                   |
+-----------------------------------------------------------------------------+

Ordinary Segre embeddings P^a x P^b can be treated as above by taking a tensor
product of GL-factors.  For P^1 x P^3, keeping only the syzygies in degree at
most 4:

+---------------------------------------------------------------------------+
|i20 : U = schurRing(QQ,u,2);                                               |
+---------------------------------------------------------------------------+
|i21 : V = schurRing(U,v,4);                                                |
+---------------------------------------------------------------------------+
|i22 : rep = u_1 * v_1;                                                     |
+---------------------------------------------------------------------------+
|i23 : M = {1_V} | apply(splice{1..5}, i -> u_i * v_i);                     |
+---------------------------------------------------------------------------+
|i24 : schurResolution(rep,M,DegreeLimit => 4)                              |
|                                                                           |
|o24 = {{(0, v  )}, {(2, u   v   )}, {(3, u   v     )}, {(4, u   v       )}}|
|             ()          1,1 1,1          2,1 1,1,1          3,1 1,1,1,1   |
|                                                                           |
|o24 : List                                                                 |
+---------------------------------------------------------------------------+

The cubic Veronese of P^2 has a rich equivariant resolution; asking for the
first few syzygies of total degree at most 4 gives the classical Koszul-type
pattern:

+-----------------------------------------------------------------------------+
|i25 : S = schurRing(QQ,s,3);                                                 |
+-----------------------------------------------------------------------------+
|i26 : rep = s_{3};                                                           |
+-----------------------------------------------------------------------------+
|i27 : M = apply(splice{0..8}, i -> s_{3*i});                                 |
+-----------------------------------------------------------------------------+
|i28 : schurResolution(rep,M,DegreeLimit => 4, SyzygyLimit => 3)              |
|                                                                             |
|o28 = {{(0, s  )}, {(2, s   )}, {(3, s      + s    + s      + s     )}, {(4, |
|             ()          4,2          6,2,1    5,4    5,3,1    4,3,2         |
|      -----------------------------------------------------------------------|
|      s      + s      + s      + s      + s      + s      + s     )}}        |
|       7,4,1    7,3,2    6,5,1    6,4,2    6,3,3    5,5,2    5,4,3           |
|                                                                             |
|o28 : List                                                                   |
+-----------------------------------------------------------------------------+

A larger example: the equivariant resolution of the residue field of Sym(V) at
rank(V) = 6 under the symmetric-group action:

+-----------------------------------------------------------------------------+
|i29 : n = 6;                                                                 |
+-----------------------------------------------------------------------------+
|i30 : Sb = schurRing(QQ,s,n,GroupActing => "Sn");                            |
+-----------------------------------------------------------------------------+
|i31 : rep = s_n + s_{n-1,1};                                                 |
+-----------------------------------------------------------------------------+
|i32 : schurResolution(rep, {s_n}, DegreeLimit => n)                          |
|                                                                             |
|o32 = {{(0, s )}, {(1, s  + s   )}, {(2, s    + s     )}, {(3, s      +      |
|             6          6    5,1          5,1    4,1,1          4,1,1        |
|      -----------------------------------------------------------------------|
|      s       )}, {(4, s        + s         )}, {(5, s          +            |
|       3,1,1,1          3,1,1,1    2,1,1,1,1          2,1,1,1,1              |
|      -----------------------------------------------------------------------|
|      s           )}, {(6, s           )}}                                   |
|       1,1,1,1,1,1          1,1,1,1,1,1                                      |
|                                                                             |
|o32 : List                                                                   |
+-----------------------------------------------------------------------------+

Ways to use schurResolution:
============================

  * "schurResolution(RingElement,List)"
  * "schurResolution(RingElement,List,List)"

For the programmer
==================

The object schurResolution, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6582:0.

schurResolution(...,DegreeLimit=>...) -- Specifies the maximal degree of syzygies to be computed
************************************************************************************************

Description
===========

This is an optional argument for the schurResolution,
routine. It specifies an upper bound for the degrees of the generators of the
syzygy modules in the equivariant resolution of an equivariant module M to be
computed by the routine. If a DegreeLimit is not specified, then it is assumed
to be equal to the maximal degree in which the module M is specified as a
representation.

+-----------------------------------------------------------------------------+
|i1 : A = schurRing(a,3,GroupActing => "Sn");                                 |
+-----------------------------------------------------------------------------+
|i2 : B = schurRing(A,b,2);                                                   |
+-----------------------------------------------------------------------------+
|i3 : rep = (a_3 + a_{2,1}) * b_1                                             |
|                                                                             |
|o3 = (a  + a   )b                                                            |
|       3    2,1  1                                                           |
|                                                                             |
|o3 : B                                                                       |
+-----------------------------------------------------------------------------+
|i4 : d = dim rep                                                             |
|                                                                             |
|o4 = 6                                                                       |
+-----------------------------------------------------------------------------+
|i5 : M = {a_3 * 1_B};                                                        |
+-----------------------------------------------------------------------------+
|i6 : sR = schurResolution(rep,M,DegreeLimit => d)                            |
|                                                                             |
|o6 = {{(0, a b  )}, {(1, (a  + a   )b )}, {(2, (a    + a     )b  + (2a  +    |
|            3 ()           3    2,1  1           2,1    1,1,1  2      3      |
|     ------------------------------------------------------------------------|
|     2a   )b   )}, {(3, a     b  + (a  + 3a    + a     )b   )}, {(4, (a    + |
|       2,1  1,1          1,1,1 3     3     2,1    1,1,1  2,1           2,1   |
|     ------------------------------------------------------------------------|
|     a     )b    + (2a  + 2a   )b   )}, {(5, (a  + a   )b   )}, {(6,         |
|      1,1,1  3,1      3     2,1  2,2           3    2,1  3,2                 |
|     ------------------------------------------------------------------------|
|     a b   )}}                                                               |
|      3 3,3                                                                  |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

Decreasing DegreeLimit truncates the output to syzygies of total degree at most
the specified value, while the representations themselves are unchanged:

+-------------------------------------------------------------+
|i7 : S = schurRing(QQ,s,3);                                  |
+-------------------------------------------------------------+
|i8 : rep = s_{2};                                            |
+-------------------------------------------------------------+
|i9 : M = {1_S,s_{2},s_{4},s_{6},s_{8},s_{10},s_{12}};        |
+-------------------------------------------------------------+
|i10 : schurResolution(rep,M)                                 |
|                                                             |
|o10 = {{(0, s  )}, {(2, s   )}, {(3, s     )}, {(4, s     )}}|
|             ()          2,2          3,2,1          3,3,2   |
|                                                             |
|o10 : List                                                   |
+-------------------------------------------------------------+
|i11 : schurResolution(rep,M,DegreeLimit => 3)                |
|                                                             |
|o11 = {{(0, s  )}, {(2, s   )}, {(3, s     )}}               |
|             ()          2,2          3,2,1                  |
|                                                             |
|o11 : List                                                   |
+-------------------------------------------------------------+

See also
========

  * schurResolution(...,SyzygyLimit=>...)
    -- Specifies the
    number of syzygy modules to be computed

Functions with optional argument named DegreeLimit:
===================================================

  * "compose(Module,Module,Module,DegreeLimit=>...)" -- see compose (Macaulay2Doc),
    -- composition as a pairing on Hom-modules
  * "End(...,DegreeLimit=>...)" -- see End (Macaulay2Doc), -- module
    of endomorphisms
  * "gb(...,DegreeLimit=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * "Hom(...,DegreeLimit=>...)" -- see Hom (Macaulay2Doc), -- module
    of homomorphisms
  * "homomorphism'(...,DegreeLimit=>...)" -- see homomorphism' (Macaulay2Doc),
    -- get the element of Hom from a homomorphism
  * kernel(...,DegreeLimit=>...) (Macaulay2Doc)
    -- stop after
    finding enough elements of a subring
  * "minimalBetti(...,DegreeLimit=>...)" -- see minimalBetti (Macaulay2Doc),
    -- minimal betti numbers of (the minimal free
    resolution of) a homogeneous ideal or module
  * normalCone(Ideal,DegreeLimit=>...) (missing documentation)
  * normalCone(Ideal,RingElement,DegreeLimit=>...) (missing documentation)
  * "pushForward(...,DegreeLimit=>...)" -- see
    pushForward(RingMap,Module) (Macaulay2Doc),
    -- compute the pushforward
    of a module along a ring map
  * quotient(...,DegreeLimit=>...) (missing documentation)
  * saturate(...,DegreeLimit=>...) (missing documentation)
  * schurResolution(...,DegreeLimit=>...)
    -- Specifies the
    maximal degree of syzygies to be computed
  * "syz(...,DegreeLimit=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

Further information
===================

  * Default value: 0
  * Function: schurResolution, -- Compute an
    ``approximate'' equivariant resolution of a module.
  * Option key: DegreeLimit (Macaulay2Doc), -- an optional
    argument
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6619:0.

schurResolution(...,SyzygyLimit=>...) -- Specifies the number of syzygy modules to be computed
**********************************************************************************************

Description
===========

This is an optional argument for the schurResolution,
routine. It specifies an upper bound for the number of syzygy modules in the
equivariant resolution of an equivariant module M to be computed by the
routine. If a SyzygyLimit is not specified, then all syzygy modules are
computed.

The example below computes the 0-th to 3-rd syzygy modules of the 5-th Veronese
embedding of P^2.

+-----------------------------------------------------------------------------+
|i1 : S = schurRing(s,3);                                                     |
+-----------------------------------------------------------------------------+
|i2 : rep = s_{5};                                                            |
+-----------------------------------------------------------------------------+
|i3 : M = {1_S,s_{5},s_{10},s_{15},s_{20},s_{25},s_{30}};                     |
+-----------------------------------------------------------------------------+
|i4 : schurResolution(rep,M,SyzygyLimit => 3)                                 |
|                                                                             |
|o4 = {{(0, s  )}, {(2, s    + s   )}, {(3, s       + s     + s       + s     |
|            ()          8,2    6,4          12,2,1    11,4    11,3,1    10,5 |
|     ------------------------------------------------------------------------|
|     + s       + s       + s    + 2s      + s      + s    + s      + s      +|
|        10,4,1    10,3,2    9,6     9,5,1    9,4,2    8,7    8,6,1    8,5,2  |
|     ------------------------------------------------------------------------|
|     s      + s      + s      + s     )}, {(4, s       + s       + 2s       +|
|      8,4,3    7,6,2    7,5,3    6,5,4          15,4,1    15,3,2     14,5,1  |
|     ------------------------------------------------------------------------|
|     s       + s       + s     + 3s       + 3s       + 2s       + s     +    |
|      14,4,2    14,3,3    13,7     13,6,1     13,5,2     13,4,3    12,8      |
|     ------------------------------------------------------------------------|
|     3s       + 4s       + 4s       + s       + s     + 3s       + 5s       +|
|       12,7,1     12,6,2     12,5,3    12,4,4    11,9     11,8,1     11,7,2  |
|     ------------------------------------------------------------------------|
|     5s       + 3s       + 2s       + 3s       + 5s       + 4s       +       |
|       11,6,3     11,5,4     10,9,1     10,8,2     10,7,3     10,6,4         |
|     ------------------------------------------------------------------------|
|     3s       + 2s      + 3s      + 4s      + 3s      + s      + 2s      +   |
|       10,5,5     9,9,2     9,8,3     9,7,4     9,6,5    8,8,4     8,7,5     |
|     ------------------------------------------------------------------------|
|     s     )}}                                                               |
|      7,7,6                                                                  |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Lowering SyzygyLimit simply chops the output at the requested homological
position.  For the quadratic Veronese of P^2, asking for only the first syzygy
module yields:

+------------------------------------------------------+
|i5 : T = schurRing(QQ,t,3);                           |
+------------------------------------------------------+
|i6 : rep2 = t_{2};                                    |
+------------------------------------------------------+
|i7 : M2 = {1_T,t_{2},t_{4},t_{6},t_{8},t_{10},t_{12}};|
+------------------------------------------------------+
|i8 : schurResolution(rep2,M2,SyzygyLimit => 1)        |
|                                                      |
|o8 = {{(0, t  )}, {(2, t   )}}                        |
|            ()          2,2                           |
|                                                      |
|o8 : List                                             |
+------------------------------------------------------+
|i9 : schurResolution(rep2,M2,SyzygyLimit => 2)        |
|                                                      |
|o9 = {{(0, t  )}, {(2, t   )}, {(3, t     )}}         |
|            ()          2,2          3,2,1            |
|                                                      |
|o9 : List                                             |
+------------------------------------------------------+

See also
========

  * schurResolution(...,DegreeLimit=>...)
    -- Specifies the
    maximal degree of syzygies to be computed

Functions with optional argument named SyzygyLimit:
===================================================

  * "gb(...,SyzygyLimit=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * schurResolution(...,SyzygyLimit=>...)
    -- Specifies the
    number of syzygy modules to be computed
  * "syz(...,SyzygyLimit=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix

Further information
===================

  * Default value: 0
  * Function: schurResolution, -- Compute an
    ``approximate'' equivariant resolution of a module.
  * Option key: SyzygyLimit (Macaulay2Doc), -- an optional
    argument
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6656:0.

SchurRing -- The class of all Schur rings
*****************************************

Description
===========

A Schur ring is the representation ring for the general linear group of n\times
n matrices, and one can be constructed with schurRing.

+--------------------------+
|i1 : S = schurRing(QQ,s,4)|
|                          |
|o1 = S                    |
|                          |
|o1 : SchurRing            |
+--------------------------+

Alternatively, its elements can be interpreted as virtual characters of
symmetric groups, by setting the value of the option GroupActing,
to "Sn".

+----------------------------------------------+
|i2 : Q = schurRing(QQ,q,4,GroupActing => "Sn")|
|                                              |
|o2 = Q                                        |
|                                              |
|o2 : SchurRing                                |
+----------------------------------------------+

The element corresponding to the Young diagram \{3,2,1\}, is obtained as
follows.

+--------------+
|i3 : s_{3,2,1}|
|              |
|o3 = s        |
|      3,2,1   |
|              |
|o3 : S        |
+--------------+

Alternatively, we can use a Sequence (Macaulay2Doc), instead of
a List (Macaulay2Doc), as the index of a Schur function.

+--------------+
|i4 : s_(3,2,1)|
|              |
|o4 = s        |
|      3,2,1   |
|              |
|o4 : S        |
+--------------+

For Young diagrams with only one row one can use positive integers as
subscripts.

+--------+
|i5 : q_4|
|        |
|o5 = q  |
|      4 |
|        |
|o5 : Q  |
+--------+

The name of the Schur ring can be used with a subscript to describe a symmetric
function.

+------------+
|i6 : Q_{2,2}|
|            |
|o6 = q      |
|      2,2   |
|            |
|o6 : Q      |
+------------+
|i7 : S_5    |
|            |
|o7 = s      |
|      5     |
|            |
|o7 : S      |
+------------+

The dimension of the underlying virtual GL-representation can be obtained with
dim (Macaulay2Doc).

+------------------+
|i8 : dim s_{3,2,1}|
|                  |
|o8 = 64           |
+------------------+

Multiplication in the ring comes from tensor product of representations.

+--------------------------------------------------------------+
|i9 : s_{3,2,1} * s_{1,1}                                      |
|                                                              |
|o9 = s      + s      + s        + s      + s        + s       |
|      4,3,1    4,2,2    4,2,1,1    3,3,2    3,3,1,1    3,2,2,1|
|                                                              |
|o9 : S                                                        |
+--------------------------------------------------------------+
|i10 : q_{2,1} * q_{2,1}                                       |
|                                                              |
|o10 = q  + q    + q                                           |
|       3    2,1    1,1,1                                      |
|                                                              |
|o10 : Q                                                       |
+--------------------------------------------------------------+

To extract data in an element in a SchurRing, use listForm (Macaulay2Doc),:

+-------------------------------------------------------+
|i11 : listForm (s_{3})^2                               |
|                                                       |
|o11 = {({6}, 1), ({5, 1}, 1), ({4, 2}, 1), ({3, 3}, 1)}|
|                                                       |
|o11 : List                                             |
+-------------------------------------------------------+
|i12 : q_{2,1} * q_{2,1}                                |
|                                                       |
|o12 = q  + q    + q                                    |
|       3    2,1    1,1,1                               |
|                                                       |
|o12 : Q                                                |
+-------------------------------------------------------+
|i13 : listForm oo                                      |
|                                                       |
|o13 = {({3}, 1), ({2, 1}, 1), ({1, 1, 1}, 1)}          |
|                                                       |
|o13 : List                                             |
+-------------------------------------------------------+

By varying the option GroupActing, one obtains Schur rings
for a wide range of classical groups.  The "Sp" flavor is the representation
ring of the symplectic group Sp(2n); multiplication in this ring is governed by
the Newell–Littlewood rule rather than the Littlewood–Richardson rule.

+--------------------------------------------------------------------------+
|i14 : Sp = schurRing(QQ,sp,4,GroupActing => "Sp");                        |
+--------------------------------------------------------------------------+
|i15 : sp_{2,1} * sp_{1,1}                                                 |
|                                                                          |
|o15 = sp    + sp      + sp  + sp      + sp        + 2sp    + sp      + sp |
|        3,2     3,1,1     3     2,2,1     2,1,1,1      2,1     1,1,1     1|
|                                                                          |
|o15 : Sp                                                                  |
+--------------------------------------------------------------------------+
|i16 : dim sp_{2,1}                                                        |
|                                                                          |
|o16 = 160                                                                 |
+--------------------------------------------------------------------------+
|i17 : exteriorPower(2,sp_{1})                                             |
|                                                                          |
|o17 = sp    + sp                                                          |
|        1,1     ()                                                        |
|                                                                          |
|o17 : Sp                                                                  |
+--------------------------------------------------------------------------+

For the orthogonal flavor "O" one must further specify the parity of the
ambient vector space via OddOrEven.  For instance, O(5) (type
B_2) is obtained as follows.

+---------------------------------------------------------------------+
|i18 : O5 = schurRing(QQ,oo5,5,GroupActing => "O",OddOrEven => "Odd");|
+---------------------------------------------------------------------+
|i19 : dim oo5_{2,2,1}                                                |
|                                                                     |
|o19 = 5005                                                           |
+---------------------------------------------------------------------+

The rational-GL flavor "RatGL" implements virtual GL-modules whose weights may
be negative, using the (\alpha,\beta) pair convention.

+----------------------------------------------------+
|i20 : Rg = schurRing(QQ,r,3,GroupActing => "RatGL");|
+----------------------------------------------------+
|i21 : r_({2,1},{1})                                 |
|                                                    |
|o21 = r                                             |
|       {{2, 1}, {1}}                                |
|                                                    |
|o21 : Rg                                            |
+----------------------------------------------------+
|i22 : r_({1},{}) * r_({},{1})                       |
|                                                    |
|o22 = r           + r                               |
|       {{1}, {1}}    {{}, {}}                       |
|                                                    |
|o22 : Rg                                            |
+----------------------------------------------------+

One can also iterate the construction to form tensor products of Schur rings,
which is useful for bivariate characters.

+-----------------------------------------------------------------------------+
|i23 : S = schurRing(QQ,s,4);                                                 |
+-----------------------------------------------------------------------------+
|i24 : T = schurRing(S,t,3);                                                  |
+-----------------------------------------------------------------------------+
|i25 : (s_{2,1} + t_{1,1})^2                                                  |
|                                                                             |
|o25 = t    + t      + 2s   t    + (s    + s      + s    + 2s      + s        |
|       2,2    2,1,1     2,1 1,1     4,2    4,1,1    3,3     3,2,1    3,1,1,1 |
|      -----------------------------------------------------------------------|
|      + s      + s       )t                                                  |
|         2,2,2    2,2,1,1  ()                                                |
|                                                                             |
|o25 : T                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * schurRing -- Make a SchurRing
  * symmetricRing -- Make a Symmetric ring
  * GroupActing -- Specifies the group that is acting
  * Basis -- Specifies the basis to use for a Schur ring
  * OddOrEven -- Select type $B_n$ or type $D_n$ for an
    orthogonal Schur ring

Functions and methods returning a Schur ring:
=============================================

  * "schurRing(Ring,Symbol,ZZ)" -- see schurRing, -- Make a
    SchurRing
  * "schurRing(Ring,Thing)" -- see schurRing, -- Make a
    SchurRing
  * "schurRing(Ring,Thing,ZZ)" -- see schurRing, -- Make a
    SchurRing

Methods that use a Schur ring:
==============================

  * "branch(RingElement,SchurRing,SchurRing)" -- see branch, --
    Restrict a Schur, Sp, or O character along a two-factor subgroup
  * coefficientRing(SchurRing), --
    Coefficient ring of a Schur ring
  * numgens(SchurRing) -- Number of generators
    of Schur ring.
  * "SchurRing _ List"
  * "SchurRing _ Sequence"
  * "SchurRing _ ZZ"
  * specialize(RingElement,ZZ,SchurRing) (missing documentation)
  * "toGL(RingElement,SchurRing)" -- see toGL, -- Express an
    element in the plain GL Schur basis
  * "toM(RingElement,SchurRing)" -- see toM, -- Monomial (m-) basis
    representation
  * "toO(RingElement,SchurRing)" -- see toO, -- Expansion in the
    basis of orthogonal characters
  * "toRatGL(RingElement,SchurRing)" -- see toRatGL, -- Lift a
    Schur (GL, SL) character into a rational-GL Schur ring
  * "toS(RingElement,SchurRing)" -- see toS, -- Schur (s-) basis
    representation
  * "toSn(RingElement,SchurRing)" -- see toSn, -- Promote a
    Schur-basis element into an Sn character ring
  * "toSp(RingElement,SchurRing)" -- see toSp, -- Expansion in the
    basis of symplectic characters

For the programmer
==================

The object SchurRing, is a type (Macaulay2Doc),
with ancestor classes EngineRing (Macaulay2Doc), < Ring (Macaulay2Doc)
< Type (Macaulay2Doc) < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5052:0.

schurRing -- Make a SchurRing
*****************************

Description
===========

S = schurRing(A,s,n) creates a Schur ring of degree n over the base ring A,
with variables based on the symbol s. This is the representation ring for the
general linear group of n by n matrices, tensored with the ring A. If s is
already assigned a value as a variable in a ring, its base symbol will be used,
if it is possible to determine.

+-----------------------------------------------------------------------------+
|i1 : S = schurRing(QQ[x],s,3);                                               |
+-----------------------------------------------------------------------------+
|i2 : (x*s_{2,1}+s_3)^2                                                       |
|                                                                             |
|                           2                   2                 2           |
|o2 = s  + (2x + 1)s    + (x  + 2x + 1)s    + (x  + 2x)s      + (x  + 1)s    +|
|      6            5,1                 4,2             4,1,1            3,3  |
|     ------------------------------------------------------------------------|
|        2                2                                                   |
|     (2x  + 2x)s      + x s                                                  |
|                3,2,1      2,2,2                                             |
|                                                                             |
|o2 : S                                                                       |
+-----------------------------------------------------------------------------+

Alternatively, the elements of a Schur ring may be interpreted as characters of
symmetric groups. To indicate this interpretation, one has to set the value of
the option GroupActing, to "Sn".

+--------------------------------------------+
|i3 : S = schurRing(s,4,GroupActing => "Sn");|
+--------------------------------------------+
|i4 : exteriorPower(2,s_(3,1))               |
|                                            |
|o4 = s                                      |
|      2,1,1                                 |
|                                            |
|o4 : S                                      |
+--------------------------------------------+

If the dimension n is not specified, then one should think of S as the full
ring of symmetric functions over the base A, i.e. there is no restriction on
the number of parts of the partitions indexing the generators of S.

+--------------------------------------------------------------+
|i5 : S = schurRing(ZZ/5,t)                                    |
|                                                              |
|o5 = S                                                        |
|                                                              |
|o5 : SchurRing                                                |
+--------------------------------------------------------------+
|i6 : (t_(2,1)-t_3)^2                                          |
|                                                              |
|o6 = t  - t    - t      + 2t    + t        + t      + t       |
|      6    5,1    4,1,1     3,3    3,1,1,1    2,2,2    2,2,1,1|
|                                                              |
|o6 : S                                                        |
+--------------------------------------------------------------+

If the base ring A is not specified, then QQ (Macaulay2Doc), is used
instead.

+--------------------------------------------------+
|i7 : S = schurRing(r,2,EHPVariables => (re,rh,rp))|
|                                                  |
|o7 = S                                            |
|                                                  |
|o7 : SchurRing                                    |
+--------------------------------------------------+
|i8 : toH r_(2,1)                                  |
|                                                  |
|       3                                          |
|o8 = rh  - rh rh                                  |
|       1     1  2                                 |
|                                                  |
|o8 : QQ[re ..re , rp ..rp , rh ..rh ]             |
|          1    2    1    2    1    2              |
+--------------------------------------------------+

Beyond the default GL flavor, the options GroupActing, and
Basis, choose between the symmetric-group ("Sn"), symplectic
("Sp"), orthogonal ("O"), special-linear ("SL"), rational-GL ("RatGL"), and
monomial-basis variants.  See the main SchurRings, page for the full
landscape.

For example, the symplectic representation ring lives in its own
SchurRing, and the orthogonal flavor takes an additional
OddOrEven, option to distinguish O(2n+1) from O(2n).

+--------------------------------------------------------------------------+
|i9 : Sp = schurRing(QQ,sp,4,GroupActing => "Sp");                         |
+--------------------------------------------------------------------------+
|i10 : sp_{2,1}*sp_{1,1}                                                   |
|                                                                          |
|o10 = sp    + sp      + sp  + sp      + sp        + 2sp    + sp      + sp |
|        3,2     3,1,1     3     2,2,1     2,1,1,1      2,1     1,1,1     1|
|                                                                          |
|o10 : Sp                                                                  |
+--------------------------------------------------------------------------+
|i11 : O4 = schurRing(QQ,o,4,GroupActing => "O",OddOrEven => "Even");      |
+--------------------------------------------------------------------------+
|i12 : dim o_{3,2,1}                                                       |
|                                                                          |
|o12 = 4096                                                                |
+--------------------------------------------------------------------------+

The monomial-symmetric-function basis is activated with Basis => "Monomial",
and multiplication switches to the corresponding convolution on weak
compositions.

+------------------------------------------------+
|i13 : M = schurRing(QQ,m,4,Basis => "Monomial");|
+------------------------------------------------+
|i14 : m_{2,1} * m_{1}                           |
|                                                |
|o14 = m    + 2m    + 2m                         |
|       3,1     2,2     2,1,1                    |
|                                                |
|o14 : M                                         |
+------------------------------------------------+
|i15 : toS m_{2,1}                               |
|                                                |
|o15 = s    - 2s                                 |
|       2,1     1,1,1                            |
|                                                |
|o15 : schurRing (QQ, s, 4)                      |
+------------------------------------------------+

One can iterate schurRing, to produce a tower of Schur rings,
a convenient setting for bi-graded or bivariate character calculations.

+----------------------------+
|i16 : S = schurRing(QQ,s,4);|
+----------------------------+
|i17 : T = schurRing(S,t,3); |
+----------------------------+
|i18 : coefficientRing T     |
|                            |
|o18 = S                     |
|                            |
|o18 : SchurRing             |
+----------------------------+
|i19 : s_{1,1} * t_{2,1}     |
|                            |
|o19 = s   t                 |
|       1,1 2,1              |
|                            |
|o19 : T                     |
+----------------------------+

Passing n => infinity (or omitting the dimension) builds the stable ring of
symmetric functions, with no bound on the number of parts.

+-------------------------------------------------------------------+
|i20 : Sinf = schurRing(ZZ/7,u);                                    |
+-------------------------------------------------------------------+
|i21 : numgens Sinf                                                 |
|                                                                   |
|o21 = infinity                                                     |
|                                                                   |
|o21 : InfiniteNumber                                               |
+-------------------------------------------------------------------+
|i22 : (u_{2,1})^2                                                  |
|                                                                   |
|o22 = u    + u      + u    + 2u      + u        + u      + u       |
|       4,2    4,1,1    3,3     3,2,1    3,1,1,1    2,2,2    2,2,1,1|
|                                                                   |
|o22 : Sinf                                                         |
+-------------------------------------------------------------------+

See also
========

  * SchurRing -- The class of all Schur rings
  * symmetricRing -- Make a Symmetric ring
  * GroupActing -- Specifies the group that is acting
  * Basis -- Specifies the basis to use for a Schur ring
  * OddOrEven -- Select type $B_n$ or type $D_n$ for an
    orthogonal Schur ring

Ways to use schurRing:
======================

  * "schurRing(Ring,Symbol)"
  * "schurRing(Ring,Symbol,ZZ)"
  * "schurRing(Ring,Thing)"
  * "schurRing(Ring,Thing,ZZ)"
  * "schurRing(Thing)"
  * "schurRing(Thing,ZZ)"
  * schurRing(Ring) -- The Schur ring corresponding
    to a given Symmetric ring.

For the programmer
==================

The object schurRing, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5158:0.

schurRing(Ring) -- The Schur ring corresponding to a given Symmetric ring.
**************************************************************************

  * Function: schurRing,
  * Usage:
        S = schurRing R
  * Inputs:
      * R, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Basis, => ..., default value "Schur", Specifies the basis
        to use for a Schur ring
      * EHPVariables, => ..., default value (e,h,p),
        Specifies sequence of symbols representing e-, h-, and p-functions
      * GroupActing, => ..., default value "GL", Specifies
        the group that is acting
      * OddOrEven, => ..., default value null, Select type
        $B_n$ or type $D_n$ for an orthogonal Schur ring
      * SVariable, => ..., default value s, Specifies symbol
        representing s-functions
  * Outputs:
      * S, a Schur ring,

Description
===========

Given a ring R, the function schurRing attempts to return a Schur ring S that
is associated to R in a natural way. Namely, if the attribute R.Schur points to
a Schur ring, then the function returns that ring. If R is already a Schur
ring, then the ring R is returned. Otherwise, if the Schur level of R is at
least one, then the function constructs a Schur ring over the base ring A of R,
having the same relative dimension over A as R. If the Schur level of R is
zero, then an error is returned.

+-----------------------------+
|i1 : R = schurRing(QQ,r,6);  |
+-----------------------------+
|i2 : schurRing R             |
|                             |
|o2 = R                       |
|                             |
|o2 : SchurRing               |
+-----------------------------+
|i3 : Q = symmetricRing(QQ,3);|
+-----------------------------+
|i4 : A = schurRing Q;        |
+-----------------------------+
|i5 : schurRing Q             |
|                             |
|o5 = A                       |
|                             |
|o5 : SchurRing               |
+-----------------------------+

Passing an existing Schur ring to schurRing simply returns it, which is
convenient as a guard when a function wants to accept either a Symmetric ring
or a Schur ring as input.

+---------------------------+
|i6 : S = schurRing(QQ,s,4);|
+---------------------------+
|i7 : schurRing S === S     |
|                           |
|o7 = true                  |
+---------------------------+

For a Symmetric ring with the "Sn" interpretation, the associated Schur ring
inherits this flavor and is cached on the ring.

+---------------------------------------------------+
|i8 : Rsn = symmetricRing(QQ,4,GroupActing => "Sn");|
+---------------------------------------------------+
|i9 : Ssn = schurRing Rsn;                          |
+---------------------------------------------------+
|i10 : numgens Ssn                                  |
|                                                   |
|o10 = 4                                            |
+---------------------------------------------------+

The construction also works over polynomial coefficient rings, producing a
Schur ring with the same parameters as coefficients.

+----------------------------------+
|i11 : Rx = symmetricRing(QQ[x],3);|
+----------------------------------+
|i12 : Sx = schurRing Rx;          |
+----------------------------------+
|i13 : coefficientRing Sx          |
|                                  |
|o13 = QQ[x]                       |
|                                  |
|o13 : PolynomialRing              |
+----------------------------------+

See also
========

  * symmetricRing -- Make a Symmetric ring
  * SchurRing -- The class of all Schur rings
  * schurRing -- Make a SchurRing

Ways to use this method:
========================

  * schurRing(Ring) -- The Schur ring corresponding
    to a given Symmetric ring.
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5579:0.

SchurRingElement -- A type describing elements of a SchurRing
*************************************************************

Description
===========

Elements of any SchurRing, -- whether a GL-ring, a
symmetric-group ring, or an orthogonal/symplectic ring -- have type
SchurRingElement.  Products, sums and (in characteristic zero) rational
scalings of Schur ring elements are again of this type.

+---------------------------------------------+
|i1 : S = schurRing(s,5)                      |
|                                             |
|o1 = S                                       |
|                                             |
|o1 : SchurRing                               |
+---------------------------------------------+
|i2 : a = s_{3,2,1}                           |
|                                             |
|o2 = s                                       |
|      3,2,1                                  |
|                                             |
|o2 : S                                       |
+---------------------------------------------+
|i3 : instance(a,SchurRingElement)            |
|                                             |
|o3 = true                                    |
+---------------------------------------------+
|i4 : T = schurRing(S,t,3,GroupActing => "Sn")|
|                                             |
|o4 = T                                       |
|                                             |
|o4 : SchurRing                               |
+---------------------------------------------+
|i5 : b = t_{2,1}+t_3                         |
|                                             |
|o5 = t  + t                                  |
|      3    2,1                               |
|                                             |
|o5 : T                                       |
+---------------------------------------------+
|i6 : instance(a*b,SchurRingElement)          |
|                                             |
|o6 = true                                    |
+---------------------------------------------+

The same type is used for symplectic characters.  Multiplying two Sp-characters
stays inside the ring:

+-------------------------------------------------+
|i7 : Sp = schurRing(QQ,sp,3,GroupActing => "Sp");|
+-------------------------------------------------+
|i8 : u = sp_{2,1};                               |
+-------------------------------------------------+
|i9 : instance(u,SchurRingElement)                |
|                                                 |
|o9 = true                                        |
+-------------------------------------------------+
|i10 : instance(u*u, SchurRingElement)            |
|                                                 |
|o10 = true                                       |
+-------------------------------------------------+

For an Sn-flavored Schur ring the ordinary ring multiplication is the tensor
product of characters, while internalProduct, gives the
pointwise (Kronecker) product:

+-----------------------------------------------------+
|i11 : Sn = schurRing(QQ,c,4,GroupActing => "Sn");    |
+-----------------------------------------------------+
|i12 : internalProduct(c_{3,1}, c_{2,1,1})            |
|                                                     |
|o12 = c    + c    + c      + c                       |
|       3,1    2,2    2,1,1    1,1,1,1                |
|                                                     |
|o12 : Sn                                             |
+-----------------------------------------------------+
|i13 : instance(c_{3,1} * c_{2,1,1}, SchurRingElement)|
|                                                     |
|o13 = true                                           |
+-----------------------------------------------------+

In a two-level ring the SchurRingElement type is closed under multiplication
across levels:

+-----------------------------------+
|i14 : G = schurRing(QQ,g,3);       |
+-----------------------------------+
|i15 : H = schurRing(G,h,2);        |
+-----------------------------------+
|i16 : z = g_{1,1} * h_{2}          |
|                                   |
|o16 = g   h                        |
|       1,1 2                       |
|                                   |
|o16 : H                            |
+-----------------------------------+
|i17 : instance(z, SchurRingElement)|
|                                   |
|o17 = true                         |
+-----------------------------------+

Methods that use an object of class SchurRingElement:
=====================================================

  * dim(List,SchurRingElement), --
    dimension of representation
  * "dim(SchurRingElement)" -- see dim(List,SchurRingElement),
    -- dimension of representation
  * "dim(Thing,SchurRingElement)" -- see dim(List,SchurRingElement),
    -- dimension of representation

For the programmer
==================

The object SchurRingElement, is a type (Macaulay2Doc),
with ancestor classes RingElement (Macaulay2Doc),
< BasicList (Macaulay2Doc) <
Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6859:0.

SchurRingIndexedVariableTable
*****************************

Description
===========

This class is used as part of the implementation of a type of indexed variable
used just for Schur rings.

It is what makes the partition-indexed notation s_{3,2,1} or s_(3,2,1) work:
when you write s in a Schur ring, s is bound to a
SchurRingIndexedVariableTable, whose _ method
accepts a list, a sequence, or an integer and returns the corresponding
Schur-basis element.  The same mechanism drives the partition-indexed notation
in every flavor of SchurRing, -- monomial, symplectic,
orthogonal, symmetric-group, and rational-GL variants all share this indexing
interface.

+----------------------------------+
|i1 : S = schurRing(QQ, s, 4);     |
+----------------------------------+
|i2 : class s                      |
|                                  |
|o2 = SchurRingIndexedVariableTable|
|                                  |
|o2 : Type                         |
+----------------------------------+
|i3 : s_{2,1}                      |
|                                  |
|o3 = s                            |
|      2,1                         |
|                                  |
|o3 : S                            |
+----------------------------------+
|i4 : s_(2,1)                      |
|                                  |
|o4 = s                            |
|      2,1                         |
|                                  |
|o4 : S                            |
+----------------------------------+
|i5 : s_2                          |
|                                  |
|o5 = s                            |
|      2                           |
|                                  |
|o5 : S                            |
+----------------------------------+

Each Schur ring comes with its own indexed variable table, and partitions with
many parts print in the same compact way.

+-----------------------------+
|i6 : T = schurRing(QQ, t, 5);|
+-----------------------------+
|i7 : t_{4,3,2,1}             |
|                             |
|o7 = t                       |
|      4,3,2,1                |
|                             |
|o7 : T                       |
+-----------------------------+
|i8 : t_{1,1,1,1}             |
|                             |
|o8 = t                       |
|      1,1,1,1                |
|                             |
|o8 : T                       |
+-----------------------------+
|i9 : dim t_{4,3,2,1}         |
|                             |
|o9 = 1024                    |
+-----------------------------+

For rings with Basis => "Monomial", the same table selects the
monomial-symmetric-function basis elements instead.

+---------------------------------------------------+
|i10 : M = schurRing(QQ, m, 4, Basis => "Monomial");|
+---------------------------------------------------+
|i11 : m_{2,1}                                      |
|                                                   |
|o11 = m                                            |
|       2,1                                         |
|                                                   |
|o11 : M                                            |
+---------------------------------------------------+
|i12 : m_{2,1} * m_{1}                              |
|                                                   |
|o12 = m    + 2m    + 2m                            |
|       3,1     2,2     2,1,1                       |
|                                                   |
|o12 : M                                            |
+---------------------------------------------------+

In the rational-GL flavor, subscripts are pairs of lists encoding positive and
negative weights.

+------------------------------------------------------+
|i13 : R = schurRing(QQ, r, 3, GroupActing => "RatGL");|
+------------------------------------------------------+
|i14 : r_({2,1},{1})                                   |
|                                                      |
|o14 = r                                               |
|       {{2, 1}, {1}}                                  |
|                                                      |
|o14 : R                                               |
+------------------------------------------------------+

See also
========

  * IndexedVariableTable (Macaulay2Doc)
  * SchurRing -- The class of all Schur rings
  * schurRing -- Make a SchurRing

Methods that use an object of class SchurRingIndexedVariableTable:
==================================================================

  * "SchurRingIndexedVariableTable _ Thing"

Protected objects of class SchurRingIndexedVariableTable:
=========================================================

  * s (missing documentation)

For the programmer
==================

The object SchurRingIndexedVariableTable,
is a type (Macaulay2Doc), with ancestor classes
IndexedVariableTable (Macaulay2Doc), <
MutableHashTable (Macaulay2Doc) < HashTable (Macaulay2Doc)
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5244:0.

specialize -- Specialize a stable character to a finite rank
************************************************************

  * Usage:
        g = specialize(f, n)
        g = specialize(f, ranks)
  * Inputs:
      * f, a ring element (Macaulay2Doc), an element of a
        SchurRing, (of any GroupActing flavor)
      * n, an integer (Macaulay2Doc), the target rank (a nonnegative
        integer)
      * ranks, a list (Macaulay2Doc), a list of target ranks, one
        per schurLevel,; an entry equal to infinity leaves
        that layer unchanged
  * Optional inputs (Macaulay2Doc),:
      * OddOrEven, => ..., default value null, Select type
        $B_n$ or type $D_n$ for an orthogonal Schur ring
  * Outputs:
      * g, a ring element (Macaulay2Doc), the image of f in
        the corresponding finite-rank ring

Description
===========

Every ring produced by schurRing, comes in two sizes: the
stable ring (rank infinity), which is a universal object admitting arbitrarily
many row labels, and the finite-rank ring (rank n), on which the relevant
representation-theoretic modification rule is enforced (see
modificationRule). The function specialize bridges the two:
it maps every partition-indexed basis element of the stable ring to its image
in the finite-rank ring, collapsing or re-signing partitions that are ``too
long'' via the modification rule of Sam-Snowden-Weyman (for Sp/O/RatGL) or
simply truncating (for GL/SL/Sn).

GL specialization drops every Schur label with more than n parts:

+--------------------------------------+
|i1 : S = schurRing(QQ, s, infinity);  |
+--------------------------------------+
|i2 : f = s_{3,2,1} + s_{2,1} + s_{1}  |
|                                      |
|o2 = s      + s    + s                |
|      3,2,1    2,1    1               |
|                                      |
|o2 : S                                |
+--------------------------------------+
|i3 : specialize(f, 3)                 |
|                                      |
|o3 = glfin3      + glfin3    + glfin3 |
|           3,2,1         2,1         1|
|                                      |
|o3 : schurRing (QQ, glfin3, 3)        |
+--------------------------------------+
|i4 : specialize(f, 2)                 |
|                                      |
|o4 = glfin2    + glfin2               |
|           2,1         1              |
|                                      |
|o4 : schurRing (QQ, glfin2, 2)        |
+--------------------------------------+

Sp specialization applies the type-C modification rule: characters $sp_\lambda$
with $\ell(\lambda) > n$ are re-expressed in the finite-rank ring (possibly
with a sign, or as zero).

+-----------------------------------------------------------+
|i5 : Sp = schurRing(QQ, sp, infinity, GroupActing => "Sp");|
+-----------------------------------------------------------+
|i6 : specialize(sp_{2,1} + sp_{1,1,1}, 2)                  |
|                                                           |
|o6 = spfin2                                                |
|           2,1                                             |
|                                                           |
|o6 : schurRing (QQ, spfin2, 2)                             |
+-----------------------------------------------------------+
|i7 : specialize(sp_{1,1,1}, 1)                             |
|                                                           |
|o7 = -spfin1                                               |
|            1                                              |
|                                                           |
|o7 : schurRing (QQ, spfin1, 1)                             |
+-----------------------------------------------------------+

Concrete low-rank $Sp$ specializations show the modification in action.  At
rank 1 ($Sp(2)$), $sp_{1,1,1}$ is modified via "C" to $-sp_{1}$, and at rank 2
($Sp(4)$), $sp_{2,1,1}$ has $\ell(\lambda) = 3 > 2$ and is also modified to a
signed lower-rank character:

+------------------------------+
|i8 : specialize(sp_{1,1,1}, 1)|
|                              |
|o8 = -spfin1                  |
|            1                 |
|                              |
|o8 : schurRing (QQ, spfin1, 1)|
+------------------------------+
|i9 : specialize(sp_{2,1,1}, 1)|
|                              |
|o9 = -spfin1                  |
|            2                 |
|                              |
|o9 : schurRing (QQ, spfin1, 1)|
+------------------------------+

O specialization distinguishes type $B_n$ (O(2n+1)) from type $D_n$ (O(2n)) via
the OddOrEven, option.  If the stable ring has a stored
OddOrEven attribute, that value is used; otherwise the option must be supplied
at the call site.

+---------------------------------------------------------+
|i10 : O = schurRing(QQ, o, infinity, GroupActing => "O");|
+---------------------------------------------------------+
|i11 : specialize(o_{2,1}, 3)                             |
|                                                         |
|o11 = ofinodd3                                           |
|              2,1                                        |
|                                                         |
|o11 : schurRing (QQ, ofinodd3, 3)                        |
+---------------------------------------------------------+
|i12 : specialize(o_{2,1}, 2, OddOrEven => "Even")        |
|                                                         |
|o12 = ofineven2                                          |
|               2,1                                       |
|                                                         |
|o12 : schurRing (QQ, ofineven2, 2)                       |
+---------------------------------------------------------+

The two $O$ flavors give genuinely different images of the same partition on
the same target rank.  For $\lambda = (2,1)$ at rank 3 we compare $O(7)$ with
$O(6)$:

+-------------------------------------------------+
|i13 : specialize(o_{2,1}, 3, OddOrEven => "Odd") |
|                                                 |
|o13 = ofinodd3                                   |
|              2,1                                |
|                                                 |
|o13 : schurRing (QQ, ofinodd3, 3)                |
+-------------------------------------------------+
|i14 : specialize(o_{2,1}, 3, OddOrEven => "Even")|
|                                                 |
|o14 = ofineven3                                  |
|               2,1                               |
|                                                 |
|o14 : schurRing (QQ, ofineven3, 3)               |
+-------------------------------------------------+

SL specialization drops rows of length equal to the full rank, i.e. "columns"
of height $n$, because the determinant representation is trivial in $SL(n)$.
Here the stable $s_{3,2}$ collapses to $s_1$ in $SL(2)$, and $s_{3,3,1}$
collapses to $s_{2,2}$ in $SL(3)$:

+------------------------------------------------------------+
|i15 : SL = schurRing(QQ, sl, infinity, GroupActing => "SL");|
+------------------------------------------------------------+
|i16 : specialize(sl_{3,2}, 2)                               |
|                                                            |
|o16 = slfin2                                                |
|            1                                               |
|                                                            |
|o16 : schurRing (QQ, slfin2, 2)                             |
+------------------------------------------------------------+
|i17 : specialize(sl_{3,3,1}, 3)                             |
|                                                            |
|o17 = slfin3                                                |
|            2,2                                             |
|                                                            |
|o17 : schurRing (QQ, slfin3, 3)                             |
+------------------------------------------------------------+

Tower specialization.  For a SchurRing, obtained by iterating
the schurRing, constructor over a coefficient ring that is
itself a SchurRing, one can specialize several layers at
once.  The layers are listed from outermost to innermost, and an entry equal to
infinity leaves that layer stable.

+---------------------------------------------------------+
|i18 : A = schurRing(QQ, a, infinity);                    |
+---------------------------------------------------------+
|i19 : B = schurRing(A, b, infinity, GroupActing => "Sp");|
+---------------------------------------------------------+
|i20 : specialize(b_{1,1} * a_{2}, {2, 3})                |
|                                                         |
|o20 = glfin3 spfin2                                      |
|            2      1,1                                   |
|                                                         |
|o20 : schurRing (schurRing (QQ, glfin3, 3), spfin2, 2)   |
+---------------------------------------------------------+

In a two-layer tower of GL and Sp flavors, the outer and inner ranks can be
adjusted independently; here is the same element specialized to a second choice
of ranks:

+------------------------------------------------------+
|i21 : specialize(b_{2,1} + a_{3,1,1}, {3, 2})         |
|                                                      |
|o21 = spfin3                                          |
|            2,1                                       |
|                                                      |
|o21 : schurRing (schurRing (QQ, glfin2, 2), spfin3, 3)|
+------------------------------------------------------+

See also
========

  * schurRing -- Make a SchurRing
  * modificationRule -- Apply the Sam-Snowden-Weyman
    modification rule
  * OddOrEven -- Select type $B_n$ or type $D_n$ for an
    orthogonal Schur ring
  * toSp -- Expansion in the basis of symplectic characters
  * toO -- Expansion in the basis of orthogonal characters
  * toRatGL -- Lift a Schur (GL, SL) character into a
    rational-GL Schur ring

Ways to use specialize:
=======================

  * "specialize(RingElement,List)"
  * "specialize(RingElement,ZZ)"
  * specialize(RingElement,ZZ,SchurRing) (missing documentation)

For the programmer
==================

The object specialize, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:9116:0.

SVariable -- Specifies symbol representing s-functions
******************************************************

Description
===========

This is an optional argument for the constructor of a Symmetric ring. It
indicates the symbol to be used to denote s-functions in the associated Schur
ring. The default value is s.

+-------------------------------------------------------+
|i1 : R = symmetricRing(QQ,5,SVariable => getSymbol"s");|
+-------------------------------------------------------+
|i2 : S = schurRing R                                   |
|                                                       |
|o2 = S                                                 |
|                                                       |
|o2 : SchurRing                                         |
+-------------------------------------------------------+
|i3 : s_2^2                                             |
|                                                       |
|o3 = s  + s    + s                                     |
|      4    3,1    2,2                                  |
|                                                       |
|o3 : S                                                 |
+-------------------------------------------------------+

The chosen symbol becomes the actual indexing name for the basis elements of
the Schur ring.  Any symbol may be used; for instance, sigma yields Schur
elements sigma_\lambda which multiply by Littlewood-Richardson:

+-----------------------------------------+
|i4 : T = schurRing(QQ,sigma,4)           |
|                                         |
|o4 = T                                   |
|                                         |
|o4 : SchurRing                           |
+-----------------------------------------+
|i5 : sigma_{1,1}^2                       |
|                                         |
|o5 = sigma    + sigma      + sigma       |
|          2,2        2,1,1        1,1,1,1|
|                                         |
|o5 : T                                   |
+-----------------------------------------+

An Sn-flavored ring using a custom SVariable stores characters of the symmetric
group on that symbol:

+--------------------------------------------------+
|i6 : Sn = schurRing(QQ,sig,4,GroupActing => "Sn");|
+--------------------------------------------------+
|i7 : sig_{3,1} * sig_{2,2}                        |
|                                                  |
|o7 = sig    + sig                                 |
|        3,1      2,1,1                            |
|                                                  |
|o7 : Sn                                           |
+--------------------------------------------------+

Distinct SVariable choices allow a tensor product of two Schur rings to carry
unambiguous variable names for each factor, so a bi-representation has a clean
display:

+----------------------------+
|i8 : S = schurRing(QQ,s,3); |
+----------------------------+
|i9 : T = schurRing(S,tau,2);|
+----------------------------+
|i10 : s_{2,1} * tau_{1,1}   |
|                            |
|o10 = s   tau               |
|       2,1   1,1            |
|                            |
|o10 : T                     |
+----------------------------+

See also
========

  * EHPVariables -- Specifies sequence of symbols
    representing e-, h-, and p-functions

Functions with optional argument named SVariable:
=================================================

  * "schurRing(...,SVariable=>...)"
  * "symmetricRing(...,SVariable=>...)"

For the programmer
==================

The object SVariable, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7762:0.

symmetricFunction -- Converts class function to symmetric function
******************************************************************

  * Usage:
        f = symmetricFunction(ch,S)
  * Inputs:
      * ch, a Class function,
      * S, a ring (Macaulay2Doc), a Symmetric or Schur ring
  * Outputs:
      * f, a ring element (Macaulay2Doc), element of a
        Symmetric or Schur ring

Description
===========

Given a virtual character cF of a symmetric group, and given a Symmetric ring
S, the method computes the corresponding symmetric function as an element of S.
The conversion uses the Frobenius characteristic map: the regular
representation (n! on the identity, zero elsewhere) maps to n! e_1^n in the
e-basis, equivalently to sum_\lambda f^\lambda s_\lambda in the s-basis.

+-------------------------------------------------+
|i1 : S = symmetricRing(QQ,4);                    |
+-------------------------------------------------+
|i2 : cF = new ClassFunction from {{1,1,1,1}=>24};|
+-------------------------------------------------+
|i3 : symmetricFunction(cF,S)                     |
|                                                 |
|      4                                          |
|o3 = p                                           |
|      1                                          |
|                                                 |
|o3 : S                                           |
+-------------------------------------------------+
|i4 : symmetricFunction(cF,schurRing S)           |
|                                                 |
|o4 = s  + 3s    + 2s    + 3s      + s            |
|      4     3,1     2,2     2,1,1    1,1,1,1     |
|                                                 |
|o4 : schurRing (QQ, s, 4)                        |
+-------------------------------------------------+

The standard representation of S_4 has character given by
classFunction(s_{3,1}); passing it through symmetricFunction recovers s_{3,1}
on the SchurRing, side:

+-------------------------------------------------+
|i5 : R = symmetricRing(QQ,4);                    |
+-------------------------------------------------+
|i6 : Sch = schurRing R;                          |
+-------------------------------------------------+
|i7 : stdCh = classFunction(jacobiTrudi({3,1},R));|
+-------------------------------------------------+
|i8 : symmetricFunction(stdCh, Sch)               |
|                                                 |
|o8 = s                                           |
|      3,1                                        |
|                                                 |
|o8 : Sch                                         |
+-------------------------------------------------+

Composing classFunction with symmetricFunction is the identity on the S_n-side
of the Frobenius correspondence -- roundtripping a class function through the
symmetric function ring returns it unchanged:

+--------------------------------------+
|i9 : sF = symmetricFunction(stdCh, R);|
+--------------------------------------+
|i10 : classFunction sF == stdCh       |
|                                      |
|o10 = true                            |
+--------------------------------------+

The trivial character of S_5 has Frobenius image h_5; the sign character maps
to e_5:

+----------------------------------------------------------+
|i11 : R5 = symmetricRing(QQ,5);                           |
+----------------------------------------------------------+
|i12 : symmetricFunction(classFunction{5}, R5)             |
|                                                          |
|       1  5    1 3     1   2   1 2     1       1       1  |
|o12 = ---p  + --p p  + -p p  + -p p  + -p p  + -p p  + -p |
|      120 1   12 1 2   8 1 2   6 1 3   6 2 3   4 1 4   5 5|
|                                                          |
|o12 : R5                                                  |
+----------------------------------------------------------+
|i13 : symmetricFunction(classFunction{1,1,1,1,1}, R5)     |
|                                                          |
|       1  5    1 3     1   2   1 2     1       1       1  |
|o13 = ---p  - --p p  + -p p  + -p p  - -p p  - -p p  + -p |
|      120 1   12 1 2   8 1 2   6 1 3   6 2 3   4 1 4   5 5|
|                                                          |
|o13 : R5                                                  |
+----------------------------------------------------------+

See also
========

  * classFunction -- Converts symmetric function to class
    function

Ways to use symmetricFunction:
==============================

  * "symmetricFunction(ClassFunction,Ring)"

For the programmer
==================

The object symmetricFunction, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:7149:0.

symmetricRing -- Make a Symmetric ring
**************************************

  * Usage:
        symmetricRing(A,n)
        symmetricRing n
  * Inputs:
      * A, a ring (Macaulay2Doc),
      * n, an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Basis, => ..., default value "Schur", Specifies the basis
        to use for a Schur ring
      * EHPVariables, => ..., default value (e,h,p),
        Specifies sequence of symbols representing e-, h-, and p-functions
      * GroupActing, => ..., default value "GL", Specifies
        the group that is acting
      * OddOrEven, => ..., default value null, Select type
        $B_n$ or type $D_n$ for an orthogonal Schur ring
      * SVariable, => ..., default value s, Specifies symbol
        representing s-functions

Description
===========

The method symmetricRing creates a Symmetric ring of dimension n over a base
ring A. This is the subring of the ring of symmetric functions over the base A
consisting of polynomials in the first n elementary (or complete, or power sum)
symmetric functions. If A is not specified, then it is assumed to be QQ (Macaulay2Doc).

+-------------------------------------------+
|i1 : R = symmetricRing(QQ[x,y,z],4)        |
|                                           |
|o1 = R                                     |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : e_2*x+y*p_3+h_2                       |
|                                           |
|o2 = y*p  + x*e  + h                       |
|        3      2    2                      |
|                                           |
|o2 : R                                     |
+-------------------------------------------+
|i3 : toS oo                                |
|                                           |
|o3 = y*s  - y*s    + s  + y*s      + x*s   |
|        3      2,1    2      1,1,1      1,1|
|                                           |
|o3 : schurRing (QQ[x..z], s, 4)            |
+-------------------------------------------+

The elements of a Symmetric ring can be interpreted as characters of either
symmetric or general linear groups. This is controlled by the value of the
option GroupActing, whose default value is "GL" (general
linear group). The other possibility for its value is "Sn" (symmetric group).

+------------------------------------------------+
|i4 : R = symmetricRing(QQ,3,GroupActing => "Sn")|
|                                                |
|o4 = R                                          |
|                                                |
|o4 : PolynomialRing                             |
+------------------------------------------------+
|i5 : toE symmetricPower(2,e_2)                  |
|                                                |
|      2                                         |
|o5 = e  - e                                     |
|      1    2                                    |
|                                                |
|o5 : R                                          |
+------------------------------------------------+

The three symmetric-function generators -- elementary, complete, and power sum
-- are all accessible in the same ring, and conversions between them are
handled by toE, toH, toP, and toS.

+-----------------------------------------------------------------------------+
|i6 : R = symmetricRing(QQ,5);                                                |
+-----------------------------------------------------------------------------+
|i7 : toS ((R.pVariable 2)^3)                                                 |
|                                                                             |
|o7 = s  - s    + 3s    - 2s      - 3s    + 2s        + 3s      - 3s        + |
|      6    5,1     4,2     4,1,1     3,3     3,1,1,1     2,2,2     2,2,1,1   |
|     ------------------------------------------------------------------------|
|     s                                                                       |
|      2,1,1,1,1                                                              |
|                                                                             |
|o7 : schurRing (QQ, s, 5)                                                    |
+-----------------------------------------------------------------------------+
|i8 : toH (R.pVariable 2)                                                     |
|                                                                             |
|        2                                                                    |
|o8 = - h  + 2h                                                               |
|        1     2                                                              |
|                                                                             |
|o8 : R                                                                       |
+-----------------------------------------------------------------------------+
|i9 : toS (R.eVariable 2 * R.hVariable 2)                                     |
|                                                                             |
|o9 = s    + s                                                                |
|      3,1    2,1,1                                                           |
|                                                                             |
|o9 : schurRing (QQ, s, 5)                                                    |
+-----------------------------------------------------------------------------+

A Symmetric ring can be built over any commutative base; coefficients can be
polynomial rings, modular rings, or even other Schur rings.

+------------------------------------------------------+
|i10 : R7 = symmetricRing(ZZ/7,4);                     |
+------------------------------------------------------+
|i11 : (R7.eVariable 2)^3                              |
|                                                      |
|       3                                              |
|o11 = e                                               |
|       2                                              |
|                                                      |
|o11 : R7                                              |
+------------------------------------------------------+
|i12 : Rt = symmetricRing(QQ[t],3,GroupActing => "Sn");|
+------------------------------------------------------+
|i13 : toS(Rt.eVariable 2 * t)                         |
|                                                      |
|o13 = t*s                                             |
|         1,1                                          |
|                                                      |
|o13 : schurRing (QQ[t], s, 3)                         |
+------------------------------------------------------+

See also
========

  * SchurRing -- The class of all Schur rings
  * schurRing -- Make a SchurRing
  * eVariable -- Elementary symmetric functions in a
    Symmetric ring
  * hVariable -- Complete symmetric functions in a Symmetric
    ring
  * pVariable -- Power-sum symmetric functions in a Symmetric
    ring

Ways to use symmetricRing:
==========================

  * "symmetricRing(Ring,ZZ)"
  * "symmetricRing(ZZ)"
  * symmetricRing(Ring) -- The Symmetric ring
    corresponding to a given (Schur) ring.

For the programmer
==================

The object symmetricRing, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5312:0.

symmetricRing(Ring) -- The Symmetric ring corresponding to a given (Schur) ring.
********************************************************************************

  * Function: symmetricRing,
  * Usage:
        R = symmetricRing S
  * Inputs:
      * S, a ring (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Basis, => ..., default value "Schur", Specifies the basis
        to use for a Schur ring
      * EHPVariables, => ..., default value (e,h,p),
        Specifies sequence of symbols representing e-, h-, and p-functions
      * GroupActing, => ..., default value "GL", Specifies
        the group that is acting
      * OddOrEven, => ..., default value null, Select type
        $B_n$ or type $D_n$ for an orthogonal Schur ring
      * SVariable, => ..., default value s, Specifies symbol
        representing s-functions
  * Outputs:
      * R, a ring (Macaulay2Doc),

Description
===========

Given a (Schur) ring S, the function symmetricRing returns a (Symmetric) ring R
that is associated to S in a natural way. Namely, if the attribute
S.symmetricRing points to a ring, then the function returns that ring. If S is
not a Schur ring, then the function returns S. Otherwise, if S is a Schur ring,
then the function constructs a polynomial ring over the Symmetric ring R_A of
the base ring A of R, having the same relative dimension over R_A as S over A.

+-------------------------------------------------------+
|i1 : A = schurRing(QQ,a,6);                            |
+-------------------------------------------------------+
|i2 : B = schurRing(A,b,3);                             |
+-------------------------------------------------------+
|i3 : symmetricRing B                                   |
|                                                       |
|o3 = QQ[e ..e , p ..p , h ..h ][e ..e , p ..p , h ..h ]|
|         1   6   1   6   1   6   1   3   1   3   1   3 |
|                                                       |
|o3 : PolynomialRing                                    |
+-------------------------------------------------------+
|i4 : symmetricRing ZZ                                  |
|                                                       |
|o4 = ZZ                                                |
|                                                       |
|o4 : Ring                                              |
+-------------------------------------------------------+

For a plain Schur ring, the associated Symmetric ring is a polynomial ring in
the elementary, complete, and power-sum generators.

+-----------------------------+
|i5 : S = schurRing(QQ,s,4);  |
+-----------------------------+
|i6 : R = symmetricRing S;    |
+-----------------------------+
|i7 : (R.eVariable 2)^2       |
|                             |
|      2                      |
|o7 = e                       |
|      2                      |
|                             |
|o7 : R                       |
+-----------------------------+
|i8 : toS ((R.eVariable 2)^2) |
|                             |
|o8 = s    + s      + s       |
|      2,2    2,1,1    1,1,1,1|
|                             |
|o8 : S                       |
+-----------------------------+

The construction plays well with coefficient rings of different flavors, and
with the symmetric-group interpretation via GroupActing => "Sn".

+-------------------------------------------------+
|i9 : Ssn = schurRing(QQ,c,4,GroupActing => "Sn");|
+-------------------------------------------------+
|i10 : Rsn = symmetricRing Ssn;                   |
+-------------------------------------------------+
|i11 : numgens Rsn                                |
|                                                 |
|o11 = 12                                         |
+-------------------------------------------------+

On a tower of Schur rings, symmetricRing produces a tower of Symmetric rings
mirroring the coefficient-ring structure.

+--------------------------------+
|i12 : A = schurRing(QQ,a,3);    |
+--------------------------------+
|i13 : B = schurRing(A,b,2);     |
+--------------------------------+
|i14 : RB = symmetricRing B;     |
+--------------------------------+
|i15 : coefficientRing RB        |
|                                |
|o15 = QQ[e ..e , p ..p , h ..h ]|
|          1   3   1   3   1   3 |
|                                |
|o15 : PolynomialRing            |
+--------------------------------+

See also
========

  * schurRing -- Make a SchurRing
  * SchurRing -- The class of all Schur rings
  * symmetricRing -- Make a Symmetric ring

Ways to use this method:
========================

  * symmetricRing(Ring) -- The Symmetric ring
    corresponding to a given (Schur) ring.
-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5644:0.

toE -- Elementary symmetric (e-) basis representation
*****************************************************

  * Usage:
        fe = toE f
  * Inputs:
      * f, a ring element (Macaulay2Doc), element of a
        Symmetric or Schur ring
  * Outputs:
      * fe, a ring element (Macaulay2Doc), element of a
        Symmetric ring

Description
===========

Given a symmetric function f, the function toE yields a representation of f as
a polynomial in the elementary symmetric functions.

If f is an element of a Schur ring S then the output fe is an element of the
Symmetric ring associated to S (see symmetricRing).

+-------------------------------+
|i1 : R = symmetricRing 7;      |
+-------------------------------+
|i2 : toE(h_3*e_3)              |
|                               |
|      3                2       |
|o2 = e e  - 2e e e  + e        |
|      1 3     1 2 3    3       |
|                               |
|o2 : R                         |
+-------------------------------+
|i3 : S = schurRing(s,4)        |
|                               |
|o3 = S                         |
|                               |
|o3 : SchurRing                 |
+-------------------------------+
|i4 : toE S_{3,2,1}             |
|                               |
|               2    2          |
|o4 = e e e  - e  - e e         |
|      1 2 3    3    1 4        |
|                               |
|o4 : QQ[e ..e , p ..p , h ..h ]|
|         1   4   1   4   1   4 |
+-------------------------------+

This also works over tensor products of Symmetric/Schur rings.

+-----------------------------------------------------------------------------+
|i5 : R = schurRing(r, 4, EHPVariables => (a,b,c));                           |
+-----------------------------------------------------------------------------+
|i6 : S = schurRing(R, s, 2, EHPVariables => (x,y,z));                        |
+-----------------------------------------------------------------------------+
|i7 : T = schurRing(S, t, 3);                                                 |
+-----------------------------------------------------------------------------+
|i8 : A = symmetricRing T;                                                    |
+-----------------------------------------------------------------------------+
|i9 : f = (r_1+s_1+t_1)^2                                                     |
|                                                                             |
|o9 = t  + t    + (2r  s  + 2r s  )t  + (s  + s    + 2r s  + (r  +            |
|      2    1,1      () 1     1 ()  1     2    1,1     1 1     2              |
|     ------------------------------------------------------------------------|
|     r   )s  )t                                                              |
|      1,1  ()  ()                                                            |
|                                                                             |
|o9 : T                                                                       |
+-----------------------------------------------------------------------------+
|i10 : toE f                                                                  |
|                                                                             |
|       2                    2            2                                   |
|o10 = e  + (2x  + 2a )e  + x  + 2a x  + a                                    |
|       1      1     1  1    1     1 1    1                                   |
|                                                                             |
|o10 : A                                                                      |
+-----------------------------------------------------------------------------+

Variant bases.  When f lives in a SchurRing, with GroupActing
in $\{$"Sp", "O", "RatGL", "SL"$\}$ or Basis => "Monomial", the output is
obtained by treating the partition labels of f as plain Schur labels and
applying the Jacobi-Trudi determinant.  This is not the same as the symmetric
function representing the character of the underlying irrep. To obtain the
character expansion, first call toS, to get the plain GL Schur
expansion, and then compose with toE: toE(toS f).

+-----------------------------------------------------+
|i11 : Sp = schurRing(QQ, sp, 3, GroupActing => "Sp");|
+-----------------------------------------------------+
|i12 : toE sp_{2,1}                                   |
|                                                     |
|o12 = e e  - e                                       |
|       1 2    3                                      |
|                                                     |
|o12 : QQ[e ..e , p ..p , h ..h ]                     |
|          1   3   1   3   1   3                      |
+-----------------------------------------------------+
|i13 : toE toS sp_{2,1}                               |
|                                                     |
|o13 = e e  - e  - e                                  |
|       1 2    3    1                                 |
|                                                     |
|o13 : QQ[e ..e , p ..p , h ..h ]                     |
|          1   3   1   3   1   3                      |
+-----------------------------------------------------+

Composing toE with toS, lets you convert an arbitrary
$e$/$h$/$p$-expression into the $e$-basis via the Schur basis, which is
sometimes numerically cleaner than Newton's identities.

+-------------------------------+
|i14 : R = symmetricRing(QQ,4); |
+-------------------------------+
|i15 : toE toS (e_1 * h_2 + p_3)|
|                               |
|        3                      |
|o15 = 2e  - 4e e  + 3e         |
|        1     1 2     3        |
|                               |
|o15 : R                        |
+-------------------------------+
|i16 : toE toS (h_2^2)          |
|                               |
|       4     2      2          |
|o16 = e  - 2e e  + e           |
|       1     1 2    2          |
|                               |
|o16 : R                        |
+-------------------------------+

The names of the output variables are controlled by EHPVariables,;
toE writes its result in the first slot of that triple.

+-----------------------------------------------------------+
|i17 : Rxyz = symmetricRing(QQ, 4, EHPVariables => (x,y,z));|
+-----------------------------------------------------------+
|i18 : toE(y_3)                                             |
|                                                           |
|       3                                                   |
|o18 = x  - 2x x  + x                                       |
|       1     1 2    3                                      |
|                                                           |
|o18 : Rxyz                                                 |
+-----------------------------------------------------------+
|i19 : toE(z_2)                                             |
|                                                           |
|       2                                                   |
|o19 = x  - 2x                                              |
|       1     2                                             |
|                                                           |
|o19 : Rxyz                                                 |
+-----------------------------------------------------------+

Stable rings.  If f lives in a rank-infinite SchurRing (created with numgens =>
infinity), toE raises an error: the associated symmetric ring can only be
constructed at finite rank.  Use specialize, to fix a rank
first.

+--------------------------------------------------------------------+
|i20 : Sinf = schurRing(QQ, u, infinity);                            |
+--------------------------------------------------------------------+
|i21 : try toE u_{2,1} else "error: stable ring has no symmetricRing"|
|                                                                    |
|o21 = error: stable ring has no symmetricRing                       |
+--------------------------------------------------------------------+
|i22 : toE specialize(u_{2,1}, 3)                                    |
|                                                                    |
|o22 = e e  - e                                                      |
|       1 2    3                                                     |
|                                                                    |
|o22 : QQ[e ..e , p ..p , h ..h ]                                    |
|          1   3   1   3   1   3                                     |
+--------------------------------------------------------------------+

See also
========

  * toH -- Complete symmetric (h-) basis representation
  * toS -- Schur (s-) basis representation
  * toP -- Power-sum (p-) basis representation
  * toSymm -- Convert a Schur ring element to an element of the
    associated symmetric ring
  * specialize -- Specialize a stable character to a finite
    rank
  * EHPVariables -- Specifies sequence of symbols
    representing e-, h-, and p-functions

Ways to use toE:
================

  * "toE(RingElement)"

For the programmer
==================

The object toE, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5831:0.

toGL -- Express an element in the plain GL Schur basis
******************************************************

  * Usage:
        g = toGL f
        g = toGL(f, T)
  * Inputs:
      * f, a ring element (Macaulay2Doc), any
        symmetric-function-like element (in a SchurRing, of
        any flavor or in a symmetricRing)
      * T, a Schur ring, optional target ring; must have
        GroupActing => "GL"
  * Outputs:
      * g, a ring element (Macaulay2Doc), f re-expressed in
        the Schur basis of an associated (or user-supplied) GL character ring

Description
===========

toGL is a readability synonym for toS.  It is provided so that
calling code documenting an intent to obtain a GL character reads naturally, in
contrast to the more neutral toS.  Conversions from Basis,
"Monomial" rings and from GroupActing-variant rings ("Sp", "O", "SL", "RatGL")
are handled transparently.

+-------------------------------------------------------+
|i1 : R = symmetricRing(QQ, 4);                         |
+-------------------------------------------------------+
|i2 : toGL(R_{0} * R_{5})  -- e_1 * h_2                 |
|                                                       |
|o2 = s  + 4s    + 5s    + 6s      + 5s      + 4s       |
|      5     4,1     3,2     3,1,1     2,2,1     2,1,1,1|
|                                                       |
|o2 : schurRing (QQ, s, 4)                              |
+-------------------------------------------------------+
+-------------------------------------------+
|i3 : T = schurRing(QQ, t, 3);              |
+-------------------------------------------+
|i4 : toGL(R_{0} * R_{5}, T)                |
|                                           |
|o4 = t  + 4t    + 5t    + 6t      + 5t     |
|      5     4,1     3,2     3,1,1     2,2,1|
|                                           |
|o4 : T                                     |
+-------------------------------------------+

toGL and toS, produce the same output on symmetric-ring elements;
only the name of the function differs:

+--------------------------------------+
|i5 : toGL(e_1 * h_2) == toS(e_1 * h_2)|
|                                      |
|o5 = true                             |
+--------------------------------------+
|i6 : toGL(h_3 - p_3) == toS(h_3 - p_3)|
|                                      |
|o6 = true                             |
+--------------------------------------+

A monomial-basis Schur ring expands to the plain Schur basis in the same way as
a Kostka-inverse computation: the monomial symmetric function $m_\lambda$ is a
signed sum of Schur functions.

+--------------------------------------------------+
|i7 : M = schurRing(QQ, m, 3, Basis => "Monomial");|
+--------------------------------------------------+
|i8 : toGL m_{2,1}                                 |
|                                                  |
|o8 = s    - 2s                                    |
|      2,1     1,1,1                               |
|                                                  |
|o8 : schurRing (QQ, s, 3)                         |
+--------------------------------------------------+

Conversion from an Sp-ring applies the Koike-Terada branching rule that expands
a symplectic character in the GL Schur basis; the GL(3) Schur expansion of the
$Sp(6)$ character $sp_{2,1}$ is:

+----------------------------------------------------+
|i9 : Sp = schurRing(QQ, sp, 3, GroupActing => "Sp");|
+----------------------------------------------------+
|i10 : toGL sp_{2,1}                                 |
|                                                    |
|o10 = s    - s                                      |
|       2,1    1                                     |
|                                                    |
|o10 : schurRing (QQ, s, 3)                          |
+----------------------------------------------------+

Finally, toGL of a polynomial expression built from $e$-, $h$-, or
$p$-generators in a symmetricRing is an efficient way to ask for its Schur
decomposition:

+-------------------------------+
|i11 : U = symmetricRing(QQ, 4);|
+-------------------------------+
|i12 : toGL(e_1 * p_2 + h_3)    |
|                               |
|o12 = 2s  - s                  |
|        3    1,1,1             |
|                               |
|o12 : schurRing (QQ, s, 4)     |
+-------------------------------+

See also
========

  * toS -- Schur (s-) basis representation
  * toSn -- Promote a Schur-basis element into an Sn character
    ring
  * toSp -- Expansion in the basis of symplectic characters
  * toO -- Expansion in the basis of orthogonal characters
  * convert -- Universal dispatcher for converting between
    Schur ring flavors

Ways to use toGL:
=================

  * "toGL(RingElement)"
  * "toGL(RingElement,SchurRing)"

For the programmer
==================

The object toGL, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8817:0.

toH -- Complete symmetric (h-) basis representation
***************************************************

  * Usage:
        fh = toH f
  * Inputs:
      * f, a ring element (Macaulay2Doc), element of a
        Symmetric or Schur ring
  * Outputs:
      * fh, a ring element (Macaulay2Doc), element of a
        Symmetric ring

Description
===========

Given a symmetric function f, the function toH yields a representation of f as
a polynomial in the complete symmetric functions.

If f is an element of a Schur ring S then the output fh is an element of the
Symmetric ring associated to S (see symmetricRing).

+-------------------------------------------------------+
|i1 : R = symmetricRing 7;                              |
+-------------------------------------------------------+
|i2 : toH(h_3*e_3)                                      |
|                                                       |
|      3                2                               |
|o2 = h h  - 2h h h  + h                                |
|      1 3     1 2 3    3                               |
|                                                       |
|o2 : R                                                 |
+-------------------------------------------------------+
|i3 : S = schurRing(s,4)                                |
|                                                       |
|o3 = S                                                 |
|                                                       |
|o3 : SchurRing                                         |
+-------------------------------------------------------+
|i4 : toH S_{3,2,1}                                     |
|                                                       |
|        6     4       2 2     3                2    2  |
|o4 = - h  + 4h h  - 3h h  - 3h h  + 3h h h  - h  + h h |
|        1     1 2     1 2     1 3     1 2 3    3    1 4|
|                                                       |
|o4 : QQ[e ..e , p ..p , h ..h ]                        |
|         1   4   1   4   1   4                         |
+-------------------------------------------------------+

This also works over tensor products of Symmetric/Schur rings.

+-----------------------------------------------------------------------------+
|i5 : R = schurRing(r, 4, EHPVariables => (a,b,c));                           |
+-----------------------------------------------------------------------------+
|i6 : S = schurRing(R, s, 2, EHPVariables => (x,y,z));                        |
+-----------------------------------------------------------------------------+
|i7 : T = schurRing(S, t, 3);                                                 |
+-----------------------------------------------------------------------------+
|i8 : A = symmetricRing T;                                                    |
+-----------------------------------------------------------------------------+
|i9 : f = (r_1+s_1+t_1)^2                                                     |
|                                                                             |
|o9 = t  + t    + (2r  s  + 2r s  )t  + (s  + s    + 2r s  + (r  +            |
|      2    1,1      () 1     1 ()  1     2    1,1     1 1     2              |
|     ------------------------------------------------------------------------|
|     r   )s  )t                                                              |
|      1,1  ()  ()                                                            |
|                                                                             |
|o9 : T                                                                       |
+-----------------------------------------------------------------------------+
|i10 : toH f                                                                  |
|                                                                             |
|       2                    2            2                                   |
|o10 = h  + (2y  + 2b )h  + y  + 2b y  + b                                    |
|       1      1     1  1    1     1 1    1                                   |
|                                                                             |
|o10 : A                                                                      |
+-----------------------------------------------------------------------------+

Variant bases.  When f lives in a SchurRing, with GroupActing
in $\{$"Sp", "O", "RatGL", "SL"$\}$ or Basis => "Monomial", partition labels
are treated as plain Schur labels (Jacobi-Trudi is applied directly); the
result is not the same as the character expansion.  Use toH(toS f) for the
latter.

+--------------------------------------------------+
|i11 : O = schurRing(QQ, o, 4, GroupActing => "O");|
+--------------------------------------------------+
|i12 : toH o_{2,1}                                 |
|                                                  |
|o12 = h h  - h                                    |
|       1 2    3                                   |
|                                                  |
|o12 : QQ[e ..e , p ..p , h ..h ]                  |
|          1   4   1   4   1   4                   |
+--------------------------------------------------+
|i13 : toH toS o_{2,1}                             |
|                                                  |
|o13 = h h  - h  - h                               |
|       1 2    3    1                              |
|                                                  |
|o13 : QQ[e ..e , p ..p , h ..h ]                  |
|          1   4   1   4   1   4                   |
+--------------------------------------------------+

Roundtripping through the Schur basis recovers the original $h$-expression (up
to the usual commutative-polynomial rewriting).

+------------------------------+
|i14 : R = symmetricRing(QQ,5);|
+------------------------------+
|i15 : toH toS (h_2 * h_3)     |
|                              |
|o15 = h h                     |
|       2 3                    |
|                              |
|o15 : R                       |
+------------------------------+
|i16 : toH toE toS (h_2^2)     |
|                              |
|       2                      |
|o16 = h                       |
|       2                      |
|                              |
|o16 : R                       |
+------------------------------+

The names of the output variables follow EHPVariables,; toH
writes its result using the second name in that triple.

+-----------------------------------------------------------+
|i17 : Rxyz = symmetricRing(QQ, 4, EHPVariables => (x,y,z));|
+-----------------------------------------------------------+
|i18 : toH(x_1 * x_2)                                       |
|                                                           |
|       3                                                   |
|o18 = y  - y y                                             |
|       1    1 2                                            |
|                                                           |
|o18 : Rxyz                                                 |
+-----------------------------------------------------------+
|i19 : toH(z_3)                                             |
|                                                           |
|       3                                                   |
|o19 = y  - 3y y  + 3y                                      |
|       1     1 2     3                                     |
|                                                           |
|o19 : Rxyz                                                 |
+-----------------------------------------------------------+

Stable rings.  Rank-infinite SchurRings raise an error; use specialize,
to fix a rank first.

+--------------------------------------------------------------------+
|i20 : Sinf = schurRing(QQ, v, infinity);                            |
+--------------------------------------------------------------------+
|i21 : try toH v_{3,1} else "error: stable ring has no symmetricRing"|
|                                                                    |
|o21 = error: stable ring has no symmetricRing                       |
+--------------------------------------------------------------------+
|i22 : toH specialize(v_{3,1}, 4)                                    |
|                                                                    |
|o22 = h h  - h                                                      |
|       1 3    4                                                     |
|                                                                    |
|o22 : QQ[e ..e , p ..p , h ..h ]                                    |
|          1   4   1   4   1   4                                     |
+--------------------------------------------------------------------+

See also
========

  * toE -- Elementary symmetric (e-) basis representation
  * toS -- Schur (s-) basis representation
  * toP -- Power-sum (p-) basis representation
  * toSymm -- Convert a Schur ring element to an element of the
    associated symmetric ring
  * specialize -- Specialize a stable character to a finite
    rank
  * EHPVariables -- Specifies sequence of symbols
    representing e-, h-, and p-functions

Ways to use toH:
================

  * "toH(RingElement)"

For the programmer
==================

The object toH, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5926:0.

toM -- Monomial (m-) basis representation
*****************************************

  * Usage:
        fm = toM f
        fm = toM(f,M)

Description
===========

Given a symmetric function f, the function toM returns a representation of f as
a linear combination of monomial symmetric functions. The output is a
RingElement in a SchurRing, with Basis, =>
"Monomial", so that the basis element m_\mu represents the monomial symmetric
function indexed by the partition \mu.

Internally, the conversion uses Kostka numbers: the Schur-to-monomial
transition is s_\lambda = \sum_\mu K_{\lambda,\mu} m_\mu.

+--------------------------------+
|i1 : S = schurRing(QQ,s,4);     |
+--------------------------------+
|i2 : toM s_{2,1}                |
|                                |
|o2 = m    + 2m                  |
|      2,1     1,1,1             |
|                                |
|o2 : schurRing (QQ, m, 4)       |
+--------------------------------+
|i3 : toM s_{3}                  |
|                                |
|o3 = m  + m    + m              |
|      3    2,1    1,1,1         |
|                                |
|o3 : schurRing (QQ, m, 4)       |
+--------------------------------+
|i4 : toM (s_{2,1} + 2*s_{1,1,1})|
|                                |
|o4 = m    + 4m                  |
|      2,1     1,1,1             |
|                                |
|o4 : schurRing (QQ, m, 4)       |
+--------------------------------+

If the target monomial ring M is not specified, the first call to toM on an
element of S creates and caches an associated monomial-basis ring with the same
number of generators and the same coefficient ring as S; subsequent calls reuse
this cached ring.

+------------------------------------------+
|i5 : ring(toM s_{2,1}) === ring(toM s_{3})|
|                                          |
|o5 = true                                 |
+------------------------------------------+

Alternatively one can supply the target monomial ring explicitly.

+-----------------------------------------------+
|i6 : M = schurRing(QQ,m,4,Basis => "Monomial");|
+-----------------------------------------------+
|i7 : toM(s_{2,1},M)                            |
|                                               |
|o7 = m    + 2m                                 |
|      2,1     1,1,1                            |
|                                               |
|o7 : M                                         |
+-----------------------------------------------+

The function also accepts elements of a Symmetric ring, in which case the input
is first converted to the Schur basis via toS.

+-----------------------------+
|i8 : R = symmetricRing(QQ,4);|
+-----------------------------+
|i9 : toM(h_2 * h_1)          |
|                             |
|o9 = m  + 2m    + 3m         |
|      3     2,1     1,1,1    |
|                             |
|o9 : schurRing (QQ, m, 4)    |
+-----------------------------+

The identity h_n = \sum_\mu m_\mu, summed over all partitions of n, reflects
the fact that the Kostka numbers K_{(n),\mu} are all 1:

+------------------------------------------+
|i10 : R5 = symmetricRing(QQ,5);           |
+------------------------------------------+
|i11 : toM h_3                             |
|                                          |
|o11 = m  + m    + m                       |
|       3    2,1    1,1,1                  |
|                                          |
|o11 : schurRing (QQ, m, 5)                |
+------------------------------------------+
|i12 : toM h_4                             |
|                                          |
|o12 = m  + m    + m    + m      + m       |
|       4    3,1    2,2    2,1,1    1,1,1,1|
|                                          |
|o12 : schurRing (QQ, m, 5)                |
+------------------------------------------+

Power-sum functions admit a particularly simple monomial expansion: p_n =
m_{(n)} identically, since p_n = \sum_i x_i^n.  This can be read off for any n:

+--------------------------+
|i13 : toM p_3             |
|                          |
|o13 = m                   |
|       3                  |
|                          |
|o13 : schurRing (QQ, m, 5)|
+--------------------------+
|i14 : toM p_5             |
|                          |
|o14 = m                   |
|       5                  |
|                          |
|o14 : schurRing (QQ, m, 5)|
+--------------------------+

Longer partitions can still be handled; the coefficients are the corresponding
Kostka numbers:

+-----------------------------------------------------------------------------+
|i15 : S6 = schurRing(QQ,s,6);                                                |
+-----------------------------------------------------------------------------+
|i16 : toM s_{4,1,1,1}                                                        |
|                                                                             |
|o16 = m        + m        + 4m          + m        + 4m          +           |
|       4,1,1,1    3,2,1,1     3,1,1,1,1    2,2,2,1     2,2,1,1,1             |
|      -----------------------------------------------------------------------|
|      10m                                                                    |
|         2,1,1,1,1,1                                                         |
|                                                                             |
|o16 : schurRing (QQ, m, 6)                                                   |
+-----------------------------------------------------------------------------+

The map toM is invertible via toS, so a Schur element roundtrips
through the monomial basis and back to the same Schur ring:

+-------------------------+
|i17 : f = s_{3,2,1};     |
+-------------------------+
|i18 : toS(toM f, S6) == f|
|                         |
|o18 = true               |
+-------------------------+

See also
========

  * toS -- Schur (s-) basis representation
  * toH -- Complete symmetric (h-) basis representation
  * toE -- Elementary symmetric (e-) basis representation
  * toP -- Power-sum (p-) basis representation
  * kostkaNumber -- Compute a Kostka number
  * Basis -- Specifies the basis to use for a Schur ring

Ways to use toM:
================

  * "toM(RingElement)"
  * "toM(RingElement,SchurRing)"

For the programmer
==================

The object toM, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8192:0.

toO -- Expansion in the basis of orthogonal characters
******************************************************

  * Usage:
        fo = toO f
        fo = toO(f,O)

Description
===========

Given a symmetric function f, the function toO returns the expression of f in
the basis of irreducible orthogonal characters. The output is a RingElement in
a SchurRing, with GroupActing, => "O", so
that the basis element o_\lambda stands for the irreducible O-representation
associated to the partition \lambda.

The conversion implements the inverse Koike branching formula s_\lambda =
\sum_\delta o_{\lambda/\delta}, where \delta ranges over partitions \delta
\subseteq \lambda with all parts even, and skew characters are expanded using
Littlewood-Richardson coefficients.

+--------------------------------+
|i1 : S = schurRing(QQ,s);       |
+--------------------------------+
|i2 : toO s_{2}                  |
|                                |
|o2 = o  + o                     |
|      2    ()                   |
|                                |
|o2 : schurRing (QQ, o, infinity)|
+--------------------------------+
|i3 : toO s_{1,1}                |
|                                |
|o3 = o                          |
|      1,1                       |
|                                |
|o3 : schurRing (QQ, o, infinity)|
+--------------------------------+
|i4 : toO s_{3}                  |
|                                |
|o4 = o  + o                     |
|      3    1                    |
|                                |
|o4 : schurRing (QQ, o, infinity)|
+--------------------------------+
|i5 : toO (2*s_{2,1} - s_{1,1,1})|
|                                |
|o5 = 2o    - o      + 2o        |
|       2,1    1,1,1     1       |
|                                |
|o5 : schurRing (QQ, o, infinity)|
+--------------------------------+

If the target orthogonal ring is not specified, the first call to toO on an
element of S creates and caches an associated stable orthogonal ring;
alternatively one can supply the target ring explicitly.

+----------------------------------------------+
|i6 : O = schurRing(QQ,o,4,GroupActing => "O");|
+----------------------------------------------+
|i7 : toO(s_{2,1},O)                           |
|                                              |
|o7 = o    + o                                 |
|      2,1    1                                |
|                                              |
|o7 : O                                        |
+----------------------------------------------+

The conversion is inverse to toS, on the orthogonal ring.  At stable
rank, toS(o_{(2)}) = s_{(2)} - 1 and toS(o_{(1,1)}) = s_{(1,1)}; the product
o_{(1)}^2 equals the Newell-Littlewood product o_{(2)} + o_{(1,1)} + 1.

+--------------------------------------------+
|i8 : O = schurRing(QQ,o,GroupActing => "O");|
+--------------------------------------------+
|i9 : toS o_{2}                              |
|                                            |
|o9 = s  - s                                 |
|      2    ()                               |
|                                            |
|o9 : schurRing (QQ, s, infinity)            |
+--------------------------------------------+
|i10 : toS o_{1,1}                           |
|                                            |
|o10 = s                                     |
|       1,1                                  |
|                                            |
|o10 : schurRing (QQ, s, infinity)           |
+--------------------------------------------+
|i11 : toO(toS(o_{2,1}, S), O) == o_{2,1}    |
|                                            |
|o11 = true                                  |
+--------------------------------------------+
|i12 : o_{1}*o_{1}                           |
|                                            |
|o12 = o  + o    + o                         |
|       2    1,1    ()                       |
|                                            |
|o12 : O                                     |
+--------------------------------------------+

At finite rank, the modification rule for types B_n / D_n is applied
automatically.  The tag OddOrEven, (default "Odd")
distinguishes O(2n+1) (type B_n) from O(2n) (type D_n) and is used by
dim (Macaulay2Doc), to pick the right Weyl dimension formula. Plethysm
routes through the GL Schur ring.

+----------------------------------------------------------------------+
|i13 : OB2 = schurRing(QQ,oB,2,GroupActing => "O", OddOrEven => "Odd");|
+----------------------------------------------------------------------+
|i14 : oB_{1}^2                                                        |
|                                                                      |
|o14 = oB  + oB    + oB                                                |
|        2     1,1     ()                                              |
|                                                                      |
|o14 : OB2                                                             |
+----------------------------------------------------------------------+
|i15 : dim oB_{2,2}                                                    |
|                                                                      |
|o15 = 35                                                              |
+----------------------------------------------------------------------+
|i16 : plethysm({2}, oB_{1})                                           |
|                                                                      |
|o16 = oB  + oB                                                        |
|        2     ()                                                      |
|                                                                      |
|o16 : OB2                                                             |
+----------------------------------------------------------------------+

The simplest nontrivial example of the inverse Koike branching is the second
symmetric power: s_{(2)} decomposes as o_{(2)} + 1 (the traceless part plus the
invariant form):

+---------------------------------+
|i17 : S = schurRing(QQ,s);       |
+---------------------------------+
|i18 : toO s_{2}                  |
|                                 |
|o18 = o  + o                     |
|       2    ()                   |
|                                 |
|o18 : schurRing (QQ, o, infinity)|
+---------------------------------+

The conversion composes with the other symmetric-function transitions.  One can
start from an element of a Symmetric ring expressed in e- or h-variables, and
let toO route it through the Schur basis:

+------------------------------+
|i19 : R = symmetricRing(QQ,5);|
+------------------------------+
|i20 : toO (e_2)               |
|                              |
|o20 = o                       |
|       1,1                    |
|                              |
|o20 : schurRing (QQ, o, 5)    |
+------------------------------+
|i21 : toO (h_2 * h_1)         |
|                              |
|o21 = o  + o    + 2o          |
|       3    2,1     1         |
|                              |
|o21 : schurRing (QQ, o, 5)    |
+------------------------------+

A rank comparison between odd and even orthogonal groups shows that the Weyl
dimension truly depends on the value of OddOrEven: the partition (2,1) indexes
a 105-dimensional irreducible of O(2\cdot 3+1) = O(7) and a 64-dimensional
irreducible of O(2\cdot 3) = O(6):

+----------------------------------------------------------------------------+
|i22 : Oodd  = schurRing(QQ, od, 3, GroupActing => "O", OddOrEven => "Odd"); |
+----------------------------------------------------------------------------+
|i23 : Oeven = schurRing(QQ, oe, 3, GroupActing => "O", OddOrEven => "Even");|
+----------------------------------------------------------------------------+
|i24 : dim od_{2,1}                                                          |
|                                                                            |
|o24 = 105                                                                   |
+----------------------------------------------------------------------------+
|i25 : dim oe_{2,1}                                                          |
|                                                                            |
|o25 = 64                                                                    |
+----------------------------------------------------------------------------+

See also
========

  * toSp -- Expansion in the basis of symplectic characters
  * toS -- Schur (s-) basis representation
  * GroupActing -- Specifies the group that is acting
  * OddOrEven -- Select type $B_n$ or type $D_n$ for an
    orthogonal Schur ring
  * dim (Macaulay2Doc) -- compute the Krull dimension
  * plethysm -- Plethystic operations on representations

Ways to use toO:
================

  * "toO(RingElement)"
  * "toO(RingElement,SchurRing)"

For the programmer
==================

The object toO, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8431:0.

toP -- Power-sum (p-) basis representation
******************************************

  * Usage:
        fp = toP f
  * Inputs:
      * f, a ring element (Macaulay2Doc), element of a
        Symmetric or Schur ring
  * Outputs:
      * fp, a ring element (Macaulay2Doc), element of a
        Symmetric ring

Description
===========

Given a symmetric function f, the function toP yields a representation of f as
a polynomial in the power-sum symmetric functions.

If f is an element of a Schur ring S then the output fp is an element of the
Symmetric ring associated to S (see symmetricRing).

+-----------------------------------------------------------+
|i1 : R = symmetricRing 7;                                  |
+-----------------------------------------------------------+
|i2 : toP(h_3*e_3)                                          |
|                                                           |
|      1 6   1 2 2   1 3     1 2                            |
|o2 = --p  - -p p  + -p p  + -p                             |
|     36 1   4 1 2   9 1 3   9 3                            |
|                                                           |
|o2 : R                                                     |
+-----------------------------------------------------------+
|i3 : S = schurRing(s,4)                                    |
|                                                           |
|o3 = S                                                     |
|                                                           |
|o3 : SchurRing                                             |
+-----------------------------------------------------------+
|i4 : toP S_{3,2,1}                                         |
|                                                           |
|      1 6    1 4     1 2 2    5 3     1         1 2   1 2  |
|o4 = --p  + --p p  - -p p  - --p p  + -p p p  - -p  + -p p |
|     72 1   12 1 2   8 1 2   18 1 3   6 1 2 3   9 3   4 1 4|
|                                                           |
|o4 : QQ[e ..e , p ..p , h ..h ]                            |
|         1   4   1   4   1   4                             |
+-----------------------------------------------------------+

This also works over tensor products of Symmetric/Schur rings.

+-----------------------------------------------------------------------------+
|i5 : R = schurRing(r, 4, EHPVariables => (a,b,c));                           |
+-----------------------------------------------------------------------------+
|i6 : S = schurRing(R, s, 2, EHPVariables => (x,y,z));                        |
+-----------------------------------------------------------------------------+
|i7 : T = schurRing(S, t, 3);                                                 |
+-----------------------------------------------------------------------------+
|i8 : A = symmetricRing T;                                                    |
+-----------------------------------------------------------------------------+
|i9 : f = (r_1+s_1+t_1)^2                                                     |
|                                                                             |
|o9 = t  + t    + (2r  s  + 2r s  )t  + (s  + s    + 2r s  + (r  +            |
|      2    1,1      () 1     1 ()  1     2    1,1     1 1     2              |
|     ------------------------------------------------------------------------|
|     r   )s  )t                                                              |
|      1,1  ()  ()                                                            |
|                                                                             |
|o9 : T                                                                       |
+-----------------------------------------------------------------------------+
|i10 : toP f                                                                  |
|                                                                             |
|       2                    2            2                                   |
|o10 = p  + (2z  + 2c )p  + z  + 2c z  + c                                    |
|       1      1     1  1    1     1 1    1                                   |
|                                                                             |
|o10 : A                                                                      |
+-----------------------------------------------------------------------------+

Variant bases.  Same caveat as toE, and toH,: on elements
of a variant-basis Schur ring, labels are treated as plain Schur labels; use
toP(toS f) to get the character expansion in the power-sum basis.

+-----------------------------------------------------+
|i11 : Sp = schurRing(QQ, sp, 3, GroupActing => "Sp");|
+-----------------------------------------------------+
|i12 : toP sp_{2,1}                                   |
|                                                     |
|      1 3   1                                        |
|o12 = -p  - -p                                       |
|      3 1   3 3                                      |
|                                                     |
|o12 : QQ[e ..e , p ..p , h ..h ]                     |
|          1   3   1   3   1   3                      |
+-----------------------------------------------------+
|i13 : toP toS sp_{2,1}                               |
|                                                     |
|      1 3   1                                        |
|o13 = -p  - -p  - p                                  |
|      3 1   3 3    1                                 |
|                                                     |
|o13 : QQ[e ..e , p ..p , h ..h ]                     |
|          1   3   1   3   1   3                      |
+-----------------------------------------------------+

Composing toP with toE, or toH, exercises Newton's
identities: toP(toE f) returns f in the $p$-basis, and toH(toP f) returns it
back in the $h$-basis.

+------------------------------+
|i14 : R = symmetricRing(QQ,5);|
+------------------------------+
|i15 : toP toE (p_2 * p_3)     |
|                              |
|o15 = p p                     |
|       2 3                    |
|                              |
|o15 : R                       |
+------------------------------+
|i16 : toH toP (h_2 * h_3)     |
|                              |
|o16 = h h                     |
|       2 3                    |
|                              |
|o16 : R                       |
+------------------------------+

The output variables for toP use the third slot of EHPVariables.

+-----------------------------------------------------------+
|i17 : Rxyz = symmetricRing(QQ, 4, EHPVariables => (x,y,z));|
+-----------------------------------------------------------+
|i18 : toP(y_3)                                             |
|                                                           |
|      1 3   1       1                                      |
|o18 = -z  + -z z  + -z                                     |
|      6 1   2 1 2   3 3                                    |
|                                                           |
|o18 : Rxyz                                                 |
+-----------------------------------------------------------+
|i19 : toP(x_1 * x_2)                                       |
|                                                           |
|      1 3   1                                              |
|o19 = -z  - -z z                                           |
|      2 1   2 1 2                                          |
|                                                           |
|o19 : Rxyz                                                 |
+-----------------------------------------------------------+

Stable rings.  Rank-infinite SchurRings raise an error; use specialize,
to fix a rank first.

+--------------------------------------------------------------------+
|i20 : Sinf = schurRing(QQ, w, infinity);                            |
+--------------------------------------------------------------------+
|i21 : try toP w_{2,2} else "error: stable ring has no symmetricRing"|
|                                                                    |
|o21 = error: stable ring has no symmetricRing                       |
+--------------------------------------------------------------------+
|i22 : toP specialize(w_{2,2}, 4)                                    |
|                                                                    |
|       1 4   1 2   1                                                |
|o22 = --p  + -p  - -p p                                             |
|      12 1   4 2   3 1 3                                            |
|                                                                    |
|o22 : QQ[e ..e , p ..p , h ..h ]                                    |
|          1   4   1   4   1   4                                     |
+--------------------------------------------------------------------+

See also
========

  * toH -- Complete symmetric (h-) basis representation
  * toS -- Schur (s-) basis representation
  * toE -- Elementary symmetric (e-) basis representation
  * toSymm -- Convert a Schur ring element to an element of the
    associated symmetric ring
  * specialize -- Specialize a stable character to a finite
    rank
  * EHPVariables -- Specifies sequence of symbols
    representing e-, h-, and p-functions

Ways to use toP:
================

  * "toP(RingElement)"

For the programmer
==================

The object toP, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:6020:0.

toRatGL -- Lift a Schur (GL, SL) character into a rational-GL Schur ring
************************************************************************

  * Usage:
        g = toRatGL(f, R)
  * Inputs:
      * f, a ring element (Macaulay2Doc), an element of a
        SchurRing with GroupActing "GL" or "SL", or already "RatGL"
      * R, a Schur ring, a target SchurRing with GroupActing
        "RatGL"
  * Outputs:
      * g, a ring element (Macaulay2Doc), the image of f in
        R, with each Schur basis element $s_\lambda$ sent to the rational Schur
        character $s_{\lambda, ()}$

Description
===========

A GroupActing "RatGL" ring represents rational GL characters with bipartition
weights $(\alpha, \beta)$, where $\alpha$ is the positive part and $\beta$ the
negative part of the highest weight. See Koike, On the decomposition of tensor
products of the representations of classical groups, Adv.\ Math.\ 74 (1989).
Ordinary GL/SL Schur characters $s_\lambda$ embed as rational characters with
trivial second weight, $s_{\lambda, ()}$; toRatGL performs this embedding
coefficientwise.

The IndexedVariableTable for a RatGL ring accepts either a bipartition
($s_{\{\alpha,\beta\}}$) or a plain partition ($s_{2,1}$, which is implicitly
$s_{\{2,1\},\{\}}$).

+---------------------------------------------------------------------------+
|i1 : G = schurRing(QQ, getSymbol "g", infinity, GroupActing => "GL");      |
+---------------------------------------------------------------------------+
|i2 : R = schurRing(QQ, getSymbol "sRat", infinity, GroupActing => "RatGL");|
+---------------------------------------------------------------------------+
|i3 : toRatGL(g_{2,1} + 3 * g_1, R)                                         |
|                                                                           |
|o3 = sRat             + 3sRat                                              |
|         {{2, 1}, {}}        {{1}, {}}                                     |
|                                                                           |
|o3 : R                                                                     |
+---------------------------------------------------------------------------+

The simplest embedding sends the standard GL character $s_{1}$ to the rational
character $s_{(1),()}$.  A slightly richer input (here an LR product
re-expressed by toRatGL) goes through coefficientwise, so the GL-basis
expansion on the right matches the one on the left:

+-------------------------------------+
|i4 : toRatGL(g_{2,1}, R)             |
|                                     |
|o4 = sRat                            |
|         {{2, 1}, {}}                |
|                                     |
|o4 : R                               |
+-------------------------------------+
|i5 : toRatGL(g_{1} * g_{1}, R)       |
|                                     |
|o5 = sRat          + sRat            |
|         {{2}, {}}       {{1, 1}, {}}|
|                                     |
|o5 : R                               |
+-------------------------------------+

Rational GL characters admit negative powers of the determinant. The
bipartition $s_{(), (1)}$ is the dual of the standard representation, and the
tensor product of the standard with its dual decomposes as $s_{(1),(1)} \oplus
s_{(),()}$ (the adjoint representation plus the trivial):

+-------------------------------------------------------------------+
|i6 : Rdual = schurRing(QQ, ratD, infinity, GroupActing => "RatGL");|
+-------------------------------------------------------------------+
|i7 : ratD_{{1},{}} * ratD_{{},{1}}                                 |
|                                                                   |
|o7 = ratD           + ratD                                         |
|         {{1}, {1}}       {{}, {}}                                 |
|                                                                   |
|o7 : Rdual                                                         |
+-------------------------------------------------------------------+

If f already lives in a RatGL ring, it is re-embedded into the target R.  When
R has finite rank $n$, a pair $(\alpha,\beta)$ with $\ell(\alpha)+\ell(\beta)
\leq n$ is admissible and $s_{\alpha,\beta}$ is left unchanged; otherwise the
Koike–Terada modification rule is applied.  The rule iteratively removes a
border strip of length $L = \ell(\alpha)+\ell(\beta)-n-1$ starting at the first
box of the last row, from both $\alpha$ and $\beta$, contributing a sign
$(-1)^{c(R_\alpha)+c(R_\beta)-1}$ per step (where $c(R)$ counts the columns the
strip occupies), until the result is admissible. The character vanishes if at
some step $L = 0$ or either partition admits no border strip of the required
length.

The admissible boundary case $\ell(\alpha)+\ell(\beta) = n+1$ therefore always
vanishes ($L = 0$):

+----------------------------------------------------------------------------+
|i8 : S = schurRing(QQ, getSymbol "sStab", infinity, GroupActing => "RatGL");|
+----------------------------------------------------------------------------+
|i9 : T = schurRing(QQ, getSymbol "sFin",  3,        GroupActing => "RatGL");|
+----------------------------------------------------------------------------+
|i10 : toRatGL(sStab_{{1,1},{1,1}} + sStab_{{1},{1}}, T)                     |
|                                                                            |
|o10 = sFin                                                                  |
|          {{1}, {1}}                                                        |
|                                                                            |
|o10 : T                                                                     |
+----------------------------------------------------------------------------+

Embedding the stable bipartitions $((2,1),(\,))$, $((1,1,1),(\,))$, and
$((1),(1,1))$ into a finite-rank $GL(2)$ rational ring keeps the first and
kills the last two.  The first is admissible; the other two hit the boundary
$\ell(\alpha)+\ell(\beta) = n+1 = 3$ so $L = 0$:

+--------------------------------------------------------------------------+
|i11 : Tfin2 = schurRing(QQ, getSymbol "sFin2", 2, GroupActing => "RatGL");|
+--------------------------------------------------------------------------+
|i12 : toRatGL(sStab_{{2,1},{}}, Tfin2)                                    |
|                                                                          |
|o12 = sFin2                                                               |
|           {{2, 1}, {}}                                                   |
|                                                                          |
|o12 : Tfin2                                                               |
+--------------------------------------------------------------------------+
|i13 : toRatGL(sStab_{{1,1,1},{}}, Tfin2)                                  |
|                                                                          |
|o13 = 0                                                                   |
|                                                                          |
|o13 : Tfin2                                                               |
+--------------------------------------------------------------------------+
|i14 : toRatGL(sStab_{{1},{1,1}}, Tfin2)                                   |
|                                                                          |
|o14 = 0                                                                   |
|                                                                          |
|o14 : Tfin2                                                               |
+--------------------------------------------------------------------------+

When $\ell(\alpha)+\ell(\beta) > n+1$ the rule is genuinely non-trivial and can
produce a non-zero modified bipartition with a sign.  For instance, at $GL(3)$
with $\alpha = (4,3,2,2)$ and $\beta = (5,2,2,1,1)$ the rule removes a border
strip of length $5$ from each partition, leaving $(4,1,1)$ and $(5,1)$; a
further pass (now with $L=1$) strips one box from each, giving $(4,1)$ and
$(5)$ with an overall sign of $-1$:

+--------------------------------------------------------------------------+
|i15 : Tfin3 = schurRing(QQ, getSymbol "sFin3", 3, GroupActing => "RatGL");|
+--------------------------------------------------------------------------+
|i16 : toRatGL(sStab_{{4,3,2,2},{5,2,2,1,1}}, Tfin3)                       |
|                                                                          |
|o16 = -sFin3                                                              |
|            {{4, 1}, {5}}                                                 |
|                                                                          |
|o16 : Tfin3                                                               |
+--------------------------------------------------------------------------+

Another non-trivial example at $GL(4)$: the columns $(1^3,1^3)$ satisfy
$\ell(\alpha)+\ell(\beta) = 6 > n+1 = 5$, so one border strip of length $L = 1$
is removed from each, producing $(1^2,1^2)$ with an overall sign of $-1$:

+--------------------------------------------------------------------------+
|i17 : Tfin4 = schurRing(QQ, getSymbol "sFin4", 4, GroupActing => "RatGL");|
+--------------------------------------------------------------------------+
|i18 : toRatGL(sStab_{{1,1,1},{1,1,1}}, Tfin4)                             |
|                                                                          |
|o18 = -sFin4                                                              |
|            {{1, 1}, {1, 1}}                                              |
|                                                                          |
|o18 : Tfin4                                                               |
+--------------------------------------------------------------------------+

See also
========

  * schurRing -- Make a SchurRing
  * specialize -- Specialize a stable character to a finite
    rank
  * GroupActing -- Specifies the group that is acting

Ways to use toRatGL:
====================

  * "toRatGL(RingElement,SchurRing)"
  * toRatGL(RingElement) (missing documentation)

For the programmer
==================

The object toRatGL, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8667:0.

toS -- Schur (s-) basis representation
**************************************

  * Usage:
        fs = toS f
        fs = toS(f,S)

Description
===========

Given a symmetric function f, the function toS yields a representation of f as
a linear combination of Schur functions.

If f is an element of a Symmetric ring R and the output Schur ring S is not
specified, then the output fs is an element of the Schur ring associated to R
(see schurRing).

+-----------------------------+
|i1 : R = symmetricRing(QQ,4);|
+-----------------------------+
|i2 : fs = toS(e_1*h_2+p_3)   |
|                             |
|o2 = 2s  + s                 |
|       3    1,1,1            |
|                             |
|o2 : schurRing (QQ, s, 4)    |
+-----------------------------+
|i3 : S = schurRing(s,2);     |
+-----------------------------+
|i4 : toS(fs,S)               |
|                             |
|o4 = 2s                      |
|       3                     |
|                             |
|o4 : S                       |
+-----------------------------+

This also works over tensor products of Symmetric/Schur rings.

+-----------------------------------------------------------------------------+
|i5 : R = symmetricRing(4, EHPVariables => (a,b,c), SVariable => r);          |
+-----------------------------------------------------------------------------+
|i6 : S = symmetricRing(R, 2, EHPVariables => (x,y,z), SVariable => s);       |
+-----------------------------------------------------------------------------+
|i7 : T = symmetricRing(S, 3, SVariable => t);                                |
+-----------------------------------------------------------------------------+
|i8 : A = schurRing T;                                                        |
+-----------------------------------------------------------------------------+
|i9 : f = a_3*x_2*e_1 - b_1*z_2*p_3                                           |
|                                                                             |
|o9 = - b z p  + a x e                                                        |
|        1 2 3    3 2 1                                                       |
|                                                                             |
|o9 : T                                                                       |
+-----------------------------------------------------------------------------+
|i10 : toS f                                                                  |
|                                                                             |
|o10 = (- r s  + r s   )t  + (r s  - r s   )t    + (- r s  + r s   )t      +  |
|          1 2    1 1,1  3     1 2    1 1,1  2,1       1 2    1 1,1  1,1,1    |
|      -----------------------------------------------------------------------|
|      r     s   t                                                            |
|       1,1,1 1,1 1                                                           |
|                                                                             |
|o10 : A                                                                      |
+-----------------------------------------------------------------------------+

The Jacobi-Trudi determinant $s_\lambda = \det(h_{\lambda_i - i + j})$ is
inverted by toS: feeding a Jacobi-Trudi expression back through toS recovers a
single Schur label.

+--------------------------------+
|i11 : R = symmetricRing(QQ,5);  |
+--------------------------------+
|i12 : toS jacobiTrudi({3,2,1},R)|
|                                |
|o12 = s                         |
|       3,2,1                    |
|                                |
|o12 : schurRing (QQ, s, 5)      |
+--------------------------------+

GL to Sn.  The GL Schur basis and the Frobenius-characteristic (Sn) basis share
the same partition index set.  Combining toS with toSn, carries
coefficient data between the two flavors.

+----------------------------------------------------+
|i13 : G  = schurRing(QQ, g, 4);                     |
+----------------------------------------------------+
|i14 : Sn = schurRing(QQ, n, 4, GroupActing => "Sn");|
+----------------------------------------------------+
|i15 : a  = toSn(g_{2,1}, Sn)                        |
|                                                    |
|o15 = n                                             |
|       2,1                                          |
|                                                    |
|o15 : Sn                                            |
+----------------------------------------------------+
|i16 : toS(a, G)                                     |
|                                                    |
|o16 = g                                             |
|       2,1                                          |
|                                                    |
|o16 : G                                             |
+----------------------------------------------------+

Sp {\rm to} S {\rm to} Sp.  Elements of a variant-basis ring (e.g.\ "Sp", "O")
can be expanded into the plain GL Schur basis with toS, and the resulting
combination re-expressed in a variant-basis ring via convert.

+------------------------------------------------------+
|i17 : Sp = schurRing(QQ, sp, 4, GroupActing => "Sp"); |
+------------------------------------------------------+
|i18 : f  = toS sp_{2,1}                               |
|                                                      |
|o18 = s    - s                                        |
|       2,1    1                                       |
|                                                      |
|o18 : schurRing (QQ, s, 4)                            |
+------------------------------------------------------+
|i19 : Sp' = schurRing(QQ, sq, 4, GroupActing => "Sp");|
+------------------------------------------------------+
|i20 : convert(f, Sp')                                 |
|                                                      |
|o20 = sq                                              |
|        2,1                                           |
|                                                      |
|o20 : Sp'                                             |
+------------------------------------------------------+

See also
========

  * toH -- Complete symmetric (h-) basis representation
  * toE -- Elementary symmetric (e-) basis representation
  * toP -- Power-sum (p-) basis representation
  * toSn -- Promote a Schur-basis element into an Sn character
    ring
  * toSymm -- Convert a Schur ring element to an element of the
    associated symmetric ring
  * jacobiTrudi -- Jacobi-Trudi determinant

Ways to use toS:
================

  * "toS(RingElement)"
  * "toS(RingElement,SchurRing)"

For the programmer
==================

The object toS, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:5727:0.

toSn -- Promote a Schur-basis element into an Sn character ring
***************************************************************

  * Usage:
        g = toSn(f, T)
  * Inputs:
      * f, a ring element (Macaulay2Doc), element of a
        SchurRing, or symmetricRing,
      * T, a Schur ring, target ring; must have GroupActing
        => "Sn"
  * Outputs:
      * g, a ring element (Macaulay2Doc), the element of T
        with the same partition-indexed coefficients as f (after converting f
        to the Schur basis)

Description
===========

The GL and Sn flavors of a SchurRing, share the same partition
index set -- the distinction is in the multiplication (LR product vs.\ internal
product) and in the semantics (polynomial GL character vs.\ Frobenius
characteristic of an $S_n$-class function).  toSn simply carries the
coefficient data across.

Finite-rank targets drop partitions with more than numgens T parts.  Inputs in
a variant basis ("Sp", "O", "RatGL", "Monomial") are first expanded in the
plain Schur basis via toS.

+---------------------------------------------------+
|i1 : S  = schurRing(QQ, s,  4);                    |
+---------------------------------------------------+
|i2 : Sn = schurRing(QQ, n, 4, GroupActing => "Sn");|
+---------------------------------------------------+
|i3 : toSn(s_{2,1} + 3 * s_{1,1,1}, Sn)             |
|                                                   |
|o3 = n    + 3n                                     |
|      2,1     1,1,1                                |
|                                                   |
|o3 : Sn                                            |
+---------------------------------------------------+
+-----------------------+
|i4 : a = toSn(s_3, Sn);|
+-----------------------+
|i5 : a * a             |
|                       |
|o5 = n                 |
|      3                |
|                       |
|o5 : Sn                |
+-----------------------+

Partition labels on the two sides match, but the multiplication does not: the
GL (LR) product of $s_{2,1}$ with itself lives in degree 6, while the
$S_3$-Kronecker product of the standard representation with itself stays in
degree 3 and decomposes as $n_{3} + n_{2,1} + n_{1,1,1}$:

+-----------------------------------------------------+
|i6 : S3  = schurRing(QQ, s3, 3);                     |
+-----------------------------------------------------+
|i7 : Sn3 = schurRing(QQ, n3, 3, GroupActing => "Sn");|
+-----------------------------------------------------+
|i8 : s3_{2,1} * s3_{2,1}                             |
|                                                     |
|o8 = s3    + s3      + s3    + 2s3      + s3         |
|       4,2     4,1,1     3,3      3,2,1     2,2,2    |
|                                                     |
|o8 : S3                                              |
+-----------------------------------------------------+
|i9 : b = toSn(s3_{2,1}, Sn3);                        |
+-----------------------------------------------------+
|i10 : b * b                                          |
|                                                     |
|o10 = n3  + n3    + n3                               |
|        3     2,1     1,1,1                          |
|                                                     |
|o10 : Sn3                                            |
+-----------------------------------------------------+

Inputs in variant bases ("Sp", "O", "RatGL", "Monomial") are first expanded
through toS, so toSn also accepts symplectic or orthogonal
characters and returns the corresponding $S_n$-class function:

+-------------------------------------------------------+
|i11 : Sp  = schurRing(QQ, sp,  3, GroupActing => "Sp");|
+-------------------------------------------------------+
|i12 : toSn(sp_{2,1}, Sn3)                              |
|                                                       |
|o12 = n3    - n3                                       |
|        2,1     1                                      |
|                                                       |
|o12 : Sn3                                              |
+-------------------------------------------------------+
|i13 : Oo  = schurRing(QQ, ooX, 3, GroupActing => "O"); |
+-------------------------------------------------------+
|i14 : toSn(ooX_{2,1}, Sn3)                             |
|                                                       |
|o14 = n3    - n3                                       |
|        2,1     1                                      |
|                                                       |
|o14 : Sn3                                              |
+-------------------------------------------------------+

See also
========

  * toS -- Schur (s-) basis representation
  * toGL -- Express an element in the plain GL Schur basis
  * internalProduct -- Internal product of symmetric
    functions/class functions
  * convert -- Universal dispatcher for converting between
    Schur ring flavors

Ways to use toSn:
=================

  * "toSn(RingElement,SchurRing)"

For the programmer
==================

The object toSn, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8891:0.

toSp -- Expansion in the basis of symplectic characters
*******************************************************

  * Usage:
        fsp = toSp f
        fsp = toSp(f,Sp)

Description
===========

Given a symmetric function f, the function toSp returns the expression of f in
the basis of irreducible symplectic characters. The output is a RingElement in
a SchurRing, with GroupActing, => "Sp", so
that the basis element sp_\lambda stands for the irreducible Sp-representation
associated to the partition \lambda.

The conversion implements the inverse Koike branching formula s_\lambda =
\sum_\delta sp_{\lambda/\delta}, where \delta ranges over partitions \delta
\subseteq \lambda all of whose columns have even length (equivalently, the
parts of \delta occur in equal pairs), and skew characters are expanded using
Littlewood-Richardson coefficients.

+---------------------------------+
|i1 : S = schurRing(QQ,s);        |
+---------------------------------+
|i2 : toSp s_{2}                  |
|                                 |
|o2 = sp                          |
|       2                         |
|                                 |
|o2 : schurRing (QQ, sp, infinity)|
+---------------------------------+
|i3 : toSp s_{1,1}                |
|                                 |
|o3 = sp    + sp                  |
|       1,1     ()                |
|                                 |
|o3 : schurRing (QQ, sp, infinity)|
+---------------------------------+
|i4 : toSp s_{3,1}                |
|                                 |
|o4 = sp    + sp                  |
|       3,1     2                 |
|                                 |
|o4 : schurRing (QQ, sp, infinity)|
+---------------------------------+
|i5 : toSp (s_{2,1} + 2*s_{1,1})  |
|                                 |
|o5 = sp    + 2sp    + sp  + 2sp  |
|       2,1      1,1     1      ()|
|                                 |
|o5 : schurRing (QQ, sp, infinity)|
+---------------------------------+

If the target symplectic ring is not specified, the first call to toSp on an
element of S creates and caches an associated stable symplectic ring with the
same coefficient ring as S; subsequent calls reuse the cached ring.

+----------------------------------------------+
|i6 : ring(toSp s_{2,1}) === ring(toSp s_{3,1})|
|                                              |
|o6 = true                                     |
+----------------------------------------------+

Alternatively one can supply the target symplectic ring explicitly.

+-------------------------------------------------+
|i7 : Sp = schurRing(QQ,sp,4,GroupActing => "Sp");|
+-------------------------------------------------+
|i8 : toSp(s_{2,1},Sp)                            |
|                                                 |
|o8 = sp    + sp                                  |
|       2,1     1                                 |
|                                                 |
|o8 : Sp                                          |
+-------------------------------------------------+

The conversion is inverse to toS, on the symplectic ring, and
multiplication of symplectic characters factors through this round-trip. At
stable rank, toS(sp_{(1,1)}) = s_{(1,1)} - 1 and toS(sp_{(2,2)}) = s_{(2,2)} -
s_{(1,1)}; the product sp_{(1)}^2 equals the Newell-Littlewood product sp_{(2)}
+ sp_{(1,1)} + 1.

+------------------------------------------------------+
|i9 : Sp = schurRing(QQ,sp,GroupActing => "Sp");       |
+------------------------------------------------------+
|i10 : toS sp_{1,1}                                    |
|                                                      |
|o10 = s    - s                                        |
|       1,1    ()                                      |
|                                                      |
|o10 : schurRing (QQ, s, infinity)                     |
+------------------------------------------------------+
|i11 : toS sp_{2,2}                                    |
|                                                      |
|o11 = s    - s                                        |
|       2,2    1,1                                     |
|                                                      |
|o11 : schurRing (QQ, s, infinity)                     |
+------------------------------------------------------+
|i12 : toSp(toS(sp_{2,1}, S), Sp) == sp_{2,1}          |
|                                                      |
|o12 = true                                            |
+------------------------------------------------------+
|i13 : sp_{1}*sp_{1}                                   |
|                                                      |
|o13 = sp  + sp    + sp                                |
|        2     1,1     ()                              |
|                                                      |
|o13 : Sp                                              |
+------------------------------------------------------+
|i14 : sp_{1,1}*sp_{1,1}                               |
|                                                      |
|o14 = sp    + sp      + sp  + sp        + sp    + sp  |
|        2,2     2,1,1     2     1,1,1,1     1,1     ()|
|                                                      |
|o14 : Sp                                              |
+------------------------------------------------------+

At finite rank n (the ring parameter numVariables), the modification rule of
Sam-Snowden-Weyman is applied automatically, so characters whose partitions
exceed n rows are folded back to admissible Sp basis elements (or zero).  Weyl
dimensions are available via dim (Macaulay2Doc).  Plethysm is
supported and routes through the GL Schur ring.

+----------------------------------------------------+
|i15 : Sp4 = schurRing(QQ,sp4,2,GroupActing => "Sp");|
+----------------------------------------------------+
|i16 : sp4_{1,1}^2                                   |
|                                                    |
|o16 = sp4    + sp4  + sp4                           |
|         2,2      2      ()                         |
|                                                    |
|o16 : Sp4                                           |
+----------------------------------------------------+
|i17 : dim sp4_{2,2}                                 |
|                                                    |
|o17 = 14                                            |
+----------------------------------------------------+
|i18 : plethysm({2}, sp4_{1})                        |
|                                                    |
|o18 = sp4                                           |
|         2                                          |
|                                                    |
|o18 : Sp4                                           |
+----------------------------------------------------+

An explicit symplectic character decomposition from a Schur polynomial can be
obtained directly; linearity lets the user combine several Schur functions at
once:

+----------------------------------+
|i19 : S = schurRing(QQ,s);        |
+----------------------------------+
|i20 : toSp(s_{2,2} + s_{1,1})     |
|                                  |
|o20 = sp    + 2sp    + 2sp        |
|        2,2      1,1      ()      |
|                                  |
|o20 : schurRing (QQ, sp, infinity)|
+----------------------------------+

Plethysm of a symplectic character is well-defined through a round-trip to the
Schur basis.  Here, the plethysm of the trivial (2)-power on the defining
representation sp_{(1)} recovers the usual Sym^2 character, and toS confirms it
is s_{(2)}:

+------------------------------------------------+
|i21 : Sp = schurRing(QQ,sp,GroupActing => "Sp");|
+------------------------------------------------+
|i22 : q = plethysm({2}, sp_{1})                 |
|                                                |
|o22 = sp                                        |
|        2                                       |
|                                                |
|o22 : Sp                                        |
+------------------------------------------------+
|i23 : toS q                                     |
|                                                |
|o23 = s                                         |
|       2                                        |
|                                                |
|o23 : schurRing (QQ, s, infinity)               |
+------------------------------------------------+

At finite rank, the modification rule folds partitions that exceed the rank.
Passing s_{(2,1,1,1)} to the rank-2 symplectic ring Sp_4 returns the modified
(and much shorter) character:

+----------------------------+
|i24 : toSp(s_{2,1,1,1}, Sp4)|
|                            |
|o24 = sp4                   |
|         1                  |
|                            |
|o24 : Sp4                   |
+----------------------------+

See also
========

  * toO -- Expansion in the basis of orthogonal characters
  * toS -- Schur (s-) basis representation
  * GroupActing -- Specifies the group that is acting
  * dim (Macaulay2Doc) -- compute the Krull dimension
  * plethysm -- Plethystic operations on representations

Ways to use toSp:
=================

  * "toSp(RingElement)"
  * "toSp(RingElement,SchurRing)"

For the programmer
==================

The object toSp, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8315:0.

toSymm -- Convert a Schur ring element to an element of the associated symmetric ring
*************************************************************************************

  * Usage:
        g = toSymm f
  * Inputs:
      * f, a ring element (Macaulay2Doc), typically an
        element of a SchurRing, (scalars are returned
        unchanged)
  * Outputs:
      * g, a ring element (Macaulay2Doc), the image of f in
        the symmetricRing, attached to its parent ring

Description
===========

Every SchurRing, has an associated symmetricRing,
with variables $e_i$, $h_i$, $p_i$.  toSymm rewrites a
Schur-basis element in that symmetric ring via the Jacobi-Trudi determinant
$s_\lambda = \det(h_{\lambda_i - i + j})$.  Scalars are returned unchanged.

This is the dual of toS, and the two together let you move freely
between Schur-basis and $e$/$h$/$p$-basis representations.

+-------------------------------+
|i1 : S = schurRing(QQ, s, 4);  |
+-------------------------------+
|i2 : toSymm s_{2,1}            |
|                               |
|o2 = e e  - e                  |
|      1 2    3                 |
|                               |
|o2 : QQ[e ..e , p ..p , h ..h ]|
|         1   4   1   4   1   4 |
+-------------------------------+
+-----------+
|i3 : toS oo|
|           |
|o3 = s     |
|      2,1  |
|           |
|o3 : S     |
+-----------+

A larger partition produces a bigger Jacobi-Trudi expansion in the $e$-basis;
here is $s_{3,2,1}$ written in the symmetric ring:

+-------------------------------+
|i4 : toSymm s_{3,2,1}          |
|                               |
|               2    2          |
|o4 = e e e  - e  - e e         |
|      1 2 3    3    1 4        |
|                               |
|o4 : QQ[e ..e , p ..p , h ..h ]|
|         1   4   1   4   1   4 |
+-------------------------------+

toSymm is additive and is a left-inverse of toS, so toS toSymm is
the identity on Schur-basis elements.  It distributes over sums and scalars
just like any ring map:

+----------------------------------+
|i5 : toSymm(s_{2,1} + 3 * s_{1,1})|
|                                  |
|o5 = e e  - e  + 3e               |
|      1 2    3     2              |
|                                  |
|o5 : QQ[e ..e , p ..p , h ..h ]   |
|         1   4   1   4   1   4    |
+----------------------------------+
|i6 : toS toSymm s_{2,1} == s_{2,1}|
|                                  |
|o6 = true                         |
+----------------------------------+

In a tensor-product (two-layer) Schur ring, toSymm is applied to the outermost
layer only, so a product like $s_{2,1}\otimes t_{1,1}$ returns an element of
the symmetric ring of S times the original t factor:

+-------------------------------------------------------+
|i7 : T = schurRing(S, t, 3);                           |
+-------------------------------------------------------+
|i8 : toSymm(s_{2,1} * t_{1,1})                         |
|                                                       |
|o8 = (e e  - e )e                                      |
|       1 2    3  2                                     |
|                                                       |
|o8 : QQ[e ..e , p ..p , h ..h ][e ..e , p ..p , h ..h ]|
|         1   4   1   4   1   4   1   3   1   3   1   3 |
+-------------------------------------------------------+

See also
========

  * toS -- Schur (s-) basis representation
  * toE -- Elementary symmetric (e-) basis representation
  * toH -- Complete symmetric (h-) basis representation
  * toP -- Power-sum (p-) basis representation
  * jacobiTrudi -- Jacobi-Trudi determinant

Ways to use toSymm:
===================

  * "toSymm(Number)"
  * "toSymm(RingElement)"

For the programmer
==================

The object toSymm, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in SchurRings.m2:8735:0.