
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


This section is based upon the paper
J. H. Redfield, ``The Theory of Group-Reduced Distributions'',
\index{Redfield, J. H.}
American J. Math.,49 (1927) 433-455,
and is an application of group theory to enumeration problems.
It is a development of the work by P. A. MacMahon on the
\index{MacMahon, P. A.}
application of symmetric functions and Hammond operators to
\index{function!symmetric}
combinatorial theory.
\index{operator!Hammond}
\index{combinatorics}

The theory is based upon the power sum symmetric functions
\subscriptIt{s}{i}
which are the sum of the \eth{\it i} powers of the variables.
The cycle index of a permutation is an expression that specifies
the sizes of the cycles of a permutation, and
may be represented as a partition.
A partition of a non-negative integer \spad{n} is a collection
of positive integers called its parts whose sum is \spad{n}.
\index{cycle index}
For example, the partition
\index{partition}
\texht{$(3^2 \  2 \ 1^2)$}{\spad{3^2 2 1^2)}}
will be used to represent
\texht{$s^2_3 s_2 s^2_1$}{\spad{(s_3)^2 s_2 (s_1)^2}}
and will indicate that the permutation has two cycles of length 3,
\index{permutation}
one of length 2 and two of length 1.
The cycle index of a permutation group is the sum of the cycle indices
of its permutations divided by the number of permutations.
The cycle indices of certain groups are provided.
\xtc{
We first expose something from the library.
}{
\spadcommand{)expose EVALCYC}
}
\xtc{
The operation \spadfun{complete} returns the cycle index of the
\index{group!symmetric}
symmetric group of order \spad{n} for argument \spad{n}.
Alternatively, it is the \eth{n} complete homogeneous symmetric
function expressed in terms of power sum symmetric functions.
}{
\spadcommand{complete 1}
}
\xtc{
}{
\spadcommand{complete 2}
}
\xtc{
}{
\spadcommand{complete 3}
}
\xtc{
}{
\spadcommand{complete 7}
}
\xtc{
The operation \spadfun{elementary} computes the \eth{n}
elementary symmetric function for argument \spad{n.}
}{
\spadcommand{elementary 7}
}
\xtc{
The operation \spadfun{alternating} returns
\index{group!alternating}
the cycle index of the alternating group
having an even number of even parts in each cycle partition.
}{
\spadcommand{alternating 7}
}
\xtc{
The operation \spadfun{cyclic} returns the cycle index of the cyclic group.
\index{group!cyclic}
}{
\spadcommand{cyclic 7}
}
\xtc{
The operation \spadfun{dihedral} is the cycle index of the
\index{group!dihedral}
dihedral group.
}{
\spadcommand{dihedral 7}
}
\xtc{
The operation \spadfun{graphs} for argument \spad{n} returns
the cycle index of the group of permutations on
the edges of the complete graph with \spad{n} nodes induced by
\index{graph}
applying the symmetric group to the nodes.
}{
\spadcommand{graphs 5}
}

The cycle index of a direct product of two groups is the product
of the cycle indices of the groups.
Redfield provided two operations on two cycle indices which will
be called ``cup'' and ``cap'' here.
The \spadfun{cup} of two cycle indices is a kind of scalar product
that combines monomials for permutations with the same cycles.
The \spadfun{cap} operation provides the sum of the coefficients
of the result of the \spadfun{cup} operation which will be an
integer that enumerates what Redfield called
group-reduced distributions.

We can, for example, represent  \spad{complete 2 * complete 2}
as the set of objects \spad{a a b b} and
\spad{complete 2 * complete 1 * complete 1} as \spad{c c d e.}

\xtc{
This integer
is the number of different sets of four pairs.
}{
\spadcommand{cap(complete 2^2, complete 2*complete 1^2)}
}
For example,
\begin{verbatim}
a a b b     a a b b    a a b b   a a b b
c c d e     c d c e    c e c d   d e c c
\end{verbatim}

\xtc{
This integer
is the number of different sets of four pairs no two pairs being equal.
}{
\spadcommand{cap(elementary 2^2, complete 2*complete 1^2)}
}
For example,
\begin{verbatim}
a a b b    a a b b
c d c e    c e c d
\end{verbatim}
In this case the configurations enumerated are easily constructed,
however the theory merely enumerates them providing little help in
actually constructing them.
\xtc{
Here are the
number of 6-pairs, first from \spad{a a a b b c,} second from
\spad{d d e e f g.}
}{
\spadcommand{cap(complete 3*complete 2*complete 1,complete 2^2*complete 1^2)}
}
\xtc{
Here it is again, but with no equal pairs.
}{
\spadcommand{cap(elementary 3*elementary 2*elementary 1,complete 2^2*complete 1^2)}
}
\xtc{
}{
\spadcommand{cap(complete 3*complete 2*complete 1,elementary 2^2*elementary 1^2)}
}
\xtc{
The number of 6-triples, first from \spad{a a a b b c,} second from
\spad{d d e e f g,} third from \spad{h h i i j j.}
}{
\spadcommand{eval(cup(complete 3*complete 2*complete 1, cup(complete 2^2*complete 1^2,complete 2^3)))}
}
\xtc{
The cycle index of vertices of a square is dihedral 4.
}{
\spadcommand{square:=dihedral 4}
}
\xtc{
The number of different squares with 2 red vertices and 2 blue vertices.
}{
\spadcommand{cap(complete 2^2,square)}
}
\xtc{
The number of necklaces with 3 red beads, 2 blue beads and 2 green beads.
}{
\spadcommand{cap(complete 3*complete 2^2,dihedral 7)}
}
\xtc{
The number of graphs with 5 nodes and 7 edges.
}{
\spadcommand{cap(graphs 5,complete 7*complete 3)}
}
\xtc{
The cycle index of rotations of vertices of a cube.
}{
\spadcommand{s(x) == powerSum(x)}
}
\xtc{
}{
\spadcommand{cube:=(1/24)*(s 1^8+9*s 2^4 + 8*s 3^2*s 1^2+6*s 4^2)}
}
\xtc{
The number of cubes with 4 red vertices and 4 blue vertices.
}{
\spadcommand{cap(complete 4^2,cube)}
}
\xtc{
The number of labeled graphs with degree sequence \spad{2 2 2 1 1}
with no loops or multiple edges.
}{
\spadcommand{cap(complete 2^3*complete 1^2,wreath(elementary 4,elementary 2))}
}
\xtc{
Again, but
with loops allowed but not multiple edges.
}{
\spadcommand{cap(complete 2^3*complete 1^2,wreath(elementary 4,complete 2))}
}
\xtc{
Again, but
with multiple edges allowed, but not loops
}{
\spadcommand{cap(complete 2^3*complete 1^2,wreath(complete 4,elementary 2))}
}
\xtc{
Again, but
with both multiple edges and loops allowed
}{
\spadcommand{cap(complete 2^3*complete 1^2,wreath(complete 4,complete 2))}
}

Having constructed a cycle index for a configuration
we are at liberty to evaluate the
% is the following supposed to be s_i ??   YES
\subscriptIt{s}{i}
components any way we please.
For example we can produce enumerating generating functions.
\index{function!enumerating generating}
This is done by providing a function \spad{f} on an integer \spad{i} to the
value required of \subscriptIt{s}{i},
and then evaluating \spad{eval(f, cycleindex)}.
\xtc{
}{
\spadcommand{x: ULS(FRAC INT,'x,0) := 'x \bound{x}}
}
\xtc{
}{
\spadcommand{ZeroOrOne: INT -> ULS(FRAC INT, 'x, 0) \bound{zodec}}
}
\xtc{
}{
\spadcommand{Integers: INT -> ULS(FRAC INT, 'x, 0) \bound{idec}}
}
\xtc{
For the integers 0 and 1, or two colors.
}{
\spadcommand{ZeroOrOne n == 1+x^n \free{x zodec}\bound{zo}}
}
\xtc{
}{
\spadcommand{ZeroOrOne 5 \free{zo}}
}
\xtc{
For the integers \spad{0, 1, 2, ...} we have this.
}{
\spadcommand{Integers n == 1/(1-x^n) \free{x idec}\bound{i}}
}
\xtc{
}{
\spadcommand{Integers 5 \free{i}}
}

\xtc{
The coefficient of \texht{$x^n$}{\spad{x^n}}
is the number of graphs with 5 nodes
and \spad{n} edges.
}{
\spadcommand{eval(ZeroOrOne, graphs 5) \free{zo}}
}
\xtc{
The coefficient of \texht{$x^n$}{\spad{x^n}}  is the number of necklaces with
\spad{n} red beads and \spad{n-8} green beads.
}{
\spadcommand{eval(ZeroOrOne,dihedral 8) \free{zo}}
}
\xtc{
The coefficient of \texht{$x^n$}{\spad{x^n}} is the number of partitions of
\spad{n} into 4 or fewer parts.
}{
\spadcommand{eval(Integers,complete 4) \free{i}}
}
\xtc{
The coefficient of \texht{$x^n$}{\spad{x^n}} is the number of
partitions of \spad{n} into 4
boxes containing ordered distinct parts.
}{
\spadcommand{eval(Integers,elementary 4) \free{i}}
}
\xtc{
The coefficient of \texht{$x^n$}{\spad{x^n}} is the number of
different cubes with \spad{n} red vertices and \spad{8-n} green ones.
}{
\spadcommand{eval(ZeroOrOne,cube) \free{zo}}
}
\xtc{
The coefficient of \texht{$x^n$}{\spad{x^n}} is the number of different cubes with integers
on the vertices whose sum is \spad{n.}
}{
\spadcommand{eval(Integers,cube) \free{i}}
}
\xtc{
The coefficient of \texht{$x^n$}{\spad{x^n}} is the number of
graphs with 5 nodes and with integers on the edges whose sum is
\spad{n.}
In other words, the enumeration is of multigraphs with 5 nodes and
\spad{n} edges.
}{
\spadcommand{eval(Integers,graphs 5) \free{i}}
}
\xtc{
Graphs with 15 nodes enumerated with respect to number of edges.
}{
\spadcommand{eval(ZeroOrOne ,graphs 15) \free{zo}}
}
\xtc{
Necklaces with 7 green beads, 8 white beads, 5 yellow beads and 10
red beads.
}{
\spadcommand{cap(dihedral 30,complete 7*complete 8*complete 5*complete 10)}
}
The operation \spadfun{SFunction} is the S-function or Schur function
of a partition written
as a descending list of integers expressed in terms of power sum
symmetric functions.
\xtc{
In this case the argument partition represents a tableau shape.
For example \spad{3,2,2,1} represents a tableau with three boxes in the
first row, two boxes in the second and third rows, and one box in the
fourth row.
\spad{SFunction [3,2,2,1]}
counts the number of different tableaux of shape \spad{3, 2, 2, 1} filled
with objects with an ascending order in the columns and a
non-descending order in the rows.
}{
\spadcommand{sf3221:= SFunction [3,2,2,1] \bound{sf3221}}
}
\xtc{
This is the number filled with \spad{a a b b c c d d.}
}{
\spadcommand{cap(sf3221,complete 2^4) \free{sf3221}}
}
The configurations enumerated above are:
\begin{verbatim}
a a b    a a c    a a d
b c      b b      b b
c d      c d      c c
d        d        d
\end{verbatim}
\xtc{
This is the number of tableaux filled with \spad{1..8.}
\index{tableaux}
}{
\spadcommand{cap(sf3221, powerSum 1^8)\free{sf3221}}
}
\xtc{
The coefficient of \texht{$x^n$}{\spad{x^n}} is the number
of column strict reverse plane partitions of \spad{n} of shape
\spad{3 2 2 1.}
}{
\spadcommand{eval(Integers, sf3221)\free{i sf3221}}
}
The smallest is
\begin{verbatim}
0 0 0
1 1
2 2
3
\end{verbatim}
