<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %A  grpoper.xml                GAP documentation            Alexander Hulpke -->
<!-- %A                                                          Heiko Theißen -->
<!-- %% -->
<!-- %% -->
<!-- %Y  (C) 1998 School Math and Comp. Sci., University of St Andrews, Scotland -->
<!-- %Y  Copyright (C) 2002 The GAP Group -->
<!-- %% -->
<Chapter Label="Group Actions">
<Heading>Group Actions</Heading>

<Index>group actions</Index>
A <E>group action</E> is a triple <M>(G, \Omega, \mu)</M>,
where <M>G</M> is a group, <M>\Omega</M> a set and
<M>\mu \colon \Omega \times G \rightarrow \Omega</M> a function
that is compatible with the group arithmetic.
We call <M>\Omega</M> the <E>domain</E> of the action.
<P/>
In &GAP;, <M>\Omega</M> can be a duplicate-free collection (an object that
permits access to its elements via the <M>\Omega[n]</M> operation,
for example a list),
it does not need to be sorted (see&nbsp;<Ref Prop="IsSet"/>).
<P/>
The acting function <M>\mu</M> is a binary &GAP; function
that returns the image <M>\mu( x, g )</M> for a point
<M>x \in \Omega</M> and a group element <M>g \in G</M>.
<P/>
In &GAP;, groups always act from the right, that is
<M>\mu( \mu( x, g ), h ) = \mu( x, gh )</M>.
<P/>
&GAP; does not test whether the acting function <M>\mu</M> satisfies the
conditions for a group operation but silently assumes that is does.
(If it does not, results are unpredictable.)
<P/>
The first section of this chapter, <Ref Sect="About Group Actions"/>,
describes the various ways how operations for group actions can be called.
<P/>
Functions for several commonly used action are already built into &GAP;.
These are listed in section&nbsp;<Ref Sect="Basic Actions"/>.
<P/>
The sections <Ref Sect="The Permutation Image of an Action"/> and
<Ref Sect="Action of a group on itself"/> describe homomorphisms and mappings
associated to group actions
as well as the permutation group image of an action.
<P/>
The other sections then describe operations to compute orbits, stabilizers,
as well as properties of actions.
<P/>
Finally section&nbsp;<Ref Sect="External Sets"/> describes the concept of
<Q>external sets</Q> which represent the concept of a <E><M>G</M>-set</E>
and underly the actions mechanism.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="About Group Actions">
<Heading>About Group Actions</Heading>

<Index Subkey="operations syntax">group actions</Index>
The syntax which is used by the operations for group actions is quite
flexible.
For example we can call the operation
<Ref Oper="OrbitsDomain" Label="for a group and an action domain"/>
for the orbits of the group <A>G</A> on the domain <A>Omega</A>
in the following ways:
<P/>
<List>
<Mark><C>OrbitsDomain</C><M>( G, \Omega[, \mu] )</M></Mark>
<Item>
  The acting function <M>\mu</M> is optional.
  If it is not given, the built-in action <Ref Func="OnPoints"/>
  (which defines an action via the caret operator <C>^</C>)
  is used as a default.
</Item>
<Mark><C>OrbitsDomain</C><M>( G, \Omega, gens, acts[, \mu] )</M></Mark>
<Item>
  This second version of
  <Ref Oper="OrbitsDomain" Label="for a group and an action domain"/>
  permits one to implement an action induced by a homomorphism:
  If the group <M>H</M> acts on <M>\Omega</M> via <M>\mu</M> and
  <M>\varphi \colon G \rightarrow H</M> is a homomorphism,
  <M>G</M> acts on <M>\Omega</M> via the induced action
  <M>\mu'( x, g ) = \mu( x, g^{\varphi} )</M>.
  <P/>
  Here <M>gens</M> must be a set of generators of <M>G</M> and <M>acts</M>
  the images of <M>gens</M> under <M>\varphi</M>.
  <M>\mu</M> is the acting function for <M>H</M>.
  Again, the function <M>\mu</M> is optional
  and <Ref Func="OnPoints"/> is used as a default.
  <P/>
  The advantage of this notation is that &GAP; does not need to construct
  this homomorphism <M>\varphi</M> and the range group <A>H</A> as &GAP;
  objects.
  (If a small group <M>G</M> acts via complicated objects <M>acts</M>
  this otherwise could lead to performance problems.)
  <P/>
  &GAP; does not test whether the mapping <M>gens \mapsto acts</M>
  actually induces a homomorphism
  and the results are unpredictable if this is not the case.
</Item>
<Mark><C>OrbitsDomain</C><M>( xset )</M></Mark>
<Item>
  A third variant is to call the operation with an external set,
  which then provides <M>G</M>, <M>\Omega</M> and <M>\mu</M>.
  You will find more about external sets in
  Section&nbsp;<Ref Sect="External Sets"/>.
</Item>
</List>
<P/>
For operations like <Ref Func="Stabilizer"/> of course the domain must be
replaced by an element of the domain of the action.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Basic Actions">
<Heading>Basic Actions</Heading>

<Index>group actions</Index>
<Index>actions</Index>
<Index>group operations</Index>
&GAP; already provides acting functions for the more common actions of a
group.
For built-in operations such as <Ref Func="Stabilizer"/>
special methods are available for many of these actions.
<P/>
If one needs an action for which no acting function is provided
by the library it can be implemented via a &GAP; function that
conforms to the syntax
<P/>
<C>actfun( omega, g )</C>
<P/>
where <C>omega</C> is an element of the action domain,
<C>g</C> is an element of the acting group,
and the return value is the image of <C>omega</C> under <C>g</C>.
<P/>
For example one could define the following function that acts on pairs of
polynomials via
<Ref Func="OnIndeterminates" Label="as a permutation action"/>:
<Log><![CDATA[
OnIndeterminatesPairs:= function( polypair, g )
  return [ OnIndeterminates( polypair[1], g ),
           OnIndeterminates( polypair[2], g ) ];
end;
]]></Log>
<P/>
Note that this function <E>must</E> implement a group action from the
<E>right</E>.
This is not verified by &GAP; and results are unpredictable otherwise.

<#Include Label="OnPoints">
<#Include Label="OnRight">
<#Include Label="OnLeftInverse">
<#Include Label="OnSets">
<#Include Label="OnTuples">
<#Include Label="OnPairs">
<#Include Label="OnSetsSets">
<#Include Label="OnSetsDisjointSets">
<#Include Label="OnSetsTuples">
<#Include Label="OnTuplesSets">
<#Include Label="OnTuplesTuples">
<#Include Label="OnLines">
<#Include Label="OnIndeterminates">

<ManSection>
<Meth Name="Permuted" Arg='list, perm' Label="as a permutation action"/>

<Description>
The following example demonstrates <Ref Oper="Permuted"/> being used
to implement a permutation action on a domain:
<P/>
<Example><![CDATA[
gap> g:=Group((1,2,3),(1,2));;
gap> dom:=[ "a", "b", "c" ];;
gap> Orbit(g,dom,Permuted);
[ [ "a", "b", "c" ], [ "c", "a", "b" ], [ "b", "a", "c" ],
  [ "b", "c", "a" ], [ "a", "c", "b" ], [ "c", "b", "a" ] ]
]]></Example>
</Description>
</ManSection>


<#Include Label="OnSubspacesByCanonicalBasis">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Action on canonical representatives">
<Heading>Action on canonical representatives</Heading>

A variety of action functions assumes that the objects on which it acts are
given in a particular form, for example canonical representatives.
Affected actions are for example <Ref Func="OnSetsSets"/>,
<Ref Func="OnSetsDisjointSets"/>, <Ref Func="OnSetsTuples"/>,
<Ref Func="OnTuplesSets"/>, <Ref Func="OnLines"/> and
<Ref Func="OnSubspacesByCanonicalBasis"/>.
<P/>
If orbit seeds or domain elements are not given in the required form &GAP;
will issue an error message:
<Log><![CDATA[
gap> Orbit(SymmetricGroup(5),[[2,4],[1,3]],OnSetsSets);
Error, Action not well-defined. See the manual section
``Action on canonical representatives''.
]]></Log>
In this case the affected domain elements have to be brought in canonical
form, as documented for the respective action function.
For interactive use this is most easily done by acting with the identity
element of the group.
<P/>
(A similar error could arise if a user-defined action function is used which
actually does not implement an action from the right.)

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Orbits">
<Heading>Orbits</Heading>

If a group <M>G</M> acts on a set <M>\Omega</M>, the set of all images of
<M>x \in \Omega</M> under elements of <M>G</M> is called the
<E>orbit</E> of <M>x</M>.
The set of orbits of <M>G</M> is a partition of <M>\Omega</M>.

<#Include Label="Orbit">
<#Include Label="Orbits">
<#Include Label="OrbitsDomain">
<#Include Label="OrbitLength">
<#Include Label="OrbitLengths">
<#Include Label="OrbitLengthsDomain">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Stabilizers">
<Heading>Stabilizers</Heading>

<Index>point stabilizer</Index><Index>set stabilizer</Index>
<Index>tuple stabilizer</Index>
The <E>stabilizer</E> of a point <M>x</M> under the action of a group
<M>G</M> is the set of all those elements in <M>G</M> which fix <M>x</M>.

<#Include Label="OrbitStabilizer">
<#Include Label="Stabilizer">
<#Include Label="OrbitStabilizerAlgorithm">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Elements with Prescribed Images">
<Heading>Elements with Prescribed Images</Heading>

<Index>transporter</Index>
<#Include Label="RepresentativeAction">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="The Permutation Image of an Action">
<Heading>The Permutation Image of an Action</Heading>

When a group <M>G</M> acts on a domain <M>\Omega</M>,
an enumeration of <M>Omega</M> yields a homomorphism from <M>G</M> into
the symmetric group on <M>\{ 1, \ldots, |\Omega| \}</M>.
In &GAP;, the enumeration of <M>\Omega</M> is provided by the
<Ref Attr="Enumerator"/> value of <M>\Omega</M>
which of course is <M>\Omega</M> itself if it is a list.
<P/>
For an action homomorphism, the operation <Ref Attr="UnderlyingExternalSet"/>
will return the external set on <M>\Omega</M> which affords the action.

<#Include Label="ActionHomomorphism">
<#Include Label="Action">
<#Include Label="SparseActionHomomorphism">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Action of a group on itself">
<Heading>Action of a group on itself</Heading>

Of particular importance is the action of a group on its elements or cosets
of a subgroup.
These actions can be obtained by using
<Ref Func="ActionHomomorphism" Label="for a group, an action domain, etc."/>
for a suitable domain (for example a list of subgroups). For the following
(frequently used) types of actions however special (often particularly
efficient) functions are provided.
A special case is the regular action on all elements.

<#Include Label="FactorCosetAction">
<#Include Label="RegularActionHomomorphism">
<#Include Label="AbelianSubfactorAction">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Permutations Induced by Elements and Cycles">
<Heading>Permutations Induced by Elements and Cycles</Heading>

If only the permutation image of a single element is needed, it might not be
worth to create the action homomorphism, the following operations yield the
permutation image and cycles of a single element.

<#Include Label="Permutation">
<#Include Label="PermutationCycle">
<#Include Label="Cycle">
<#Include Label="CycleLength">
<#Include Label="Cycles">
<#Include Label="CycleLengths">
<#Include Label="CycleIndex">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Tests for Actions">
<Heading>Tests for Actions</Heading>

<#Include Label="IsTransitive:oprt">
<#Include Label="Transitivity:oprt">
<#Include Label="RankAction">
<#Include Label="IsSemiRegular">
<#Include Label="IsRegular">
<#Include Label="Earns">
<#Include Label="IsPrimitive">
<!-- %\declaration{IsFixpointFree} -->

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Block Systems">
<Heading>Block Systems</Heading>

A <E>block system</E> (system of imprimitivity) for the action of a group
<M>G</M> on an action domain <M>\Omega</M>
is a partition of <M>\Omega</M> which &ndash;as a partition&ndash;
remains invariant under the action of <M>G</M>.

For operations concerning block systems, &GAP; assumes that <M>G</M> acts
transitively on <M>\Omega</M>
(see <Ref Oper="IsTransitive" Label="for a group, an action domain, etc."/>).
One may get wrong results or error messages (perhaps at a much later stage)
if this condition is not satisfied.

<#Include Label="Blocks">
<#Include Label="MaximalBlocks">
<#Include Label="RepresentativesMinimalBlocks">
<#Include Label="AllBlocks">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="External Sets">
<Heading>External Sets</Heading>

<Index Key="G-sets"><M>G</M>-sets</Index>
When considering group actions,
sometimes the concept of a <E><M>G</M>-set</E> is used.
This is a set <M>\Omega</M> endowed with an action of <M>G</M>.
The elements of the <M>G</M>-set are the same as those of <M>\Omega</M>,
however concepts like equality and equivalence of <M>G</M>-sets do not only
consider the underlying domain <M>\Omega</M> but the group action as well.
<P/>
This concept is implemented in &GAP; via <E>external sets</E>.
<P/>
The constituents of an external set are stored in the attributes
<Ref Attr="ActingDomain"/>, <Ref Attr="FunctionAction"/> and
<Ref Attr="HomeEnumerator"/>.
<P/>
Most operations for actions are applicable as an attribute for an external
set.
<P/>
The most prominent external subsets are orbits,
see <Ref Oper="ExternalOrbit"/>.
<P/>
Many subsets of a group, such as conjugacy classes or cosets
(see&nbsp;<Ref Oper="ConjugacyClass"/> and <Ref Oper="RightCoset"/>)
are implemented as external orbits.
<P/>
External sets also are implicitly underlying action homomorphisms,
see <Ref Attr="UnderlyingExternalSet"/>
and <Ref Attr="SurjectiveActionHomomorphismAttr"/>.

<#Include Label="IsExternalSet">
<#Include Label="ExternalSet">
<#Include Label="ActingDomain">
<#Include Label="FunctionAction">
<#Include Label="HomeEnumerator">
<#Include Label="IsExternalSubset">
<#Include Label="ExternalSubset">
<#Include Label="IsExternalOrbit">
<#Include Label="ExternalOrbit">
<#Include Label="StabilizerOfExternalSet">
<#Include Label="ExternalOrbits">
<#Include Label="ExternalOrbitsStabilizers">
<#Include Label="CanonicalRepresentativeOfExternalSet">
<#Include Label="CanonicalRepresentativeDeterminatorOfExternalSet">
<#Include Label="ActorOfExternalSet">
<#Include Label="UnderlyingExternalSet">
<#Include Label="SurjectiveActionHomomorphismAttr">

</Section>
</Chapter>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %E -->