%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  grpoper.msk                GAP documentation            Alexander Hulpke
%A                                                          Heiko Theissen
%%
%A  @(#)$Id: grpoper.msk,v 1.46.2.1 2005/05/09 07:37:51 gap Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Group Actions}

\index{group actions}\atindex{G-sets}{@$G$-sets}
A *group action* is a triple $(G,<Omega>,\mu)$, where $G$ is a group,
<Omega> a set and $\mu\colon<Omega>\times G\to<Omega>$ a function (whose
action is compatible with the group arithmetic). We call <Omega> the
*domain* of the action.

In {\GAP}, <Omega> can be a duplicate-free collection (an object that
permits access to its elements via the <Omega>[<n>] operation, for example a
list), it does not need to be sorted (see~"IsSet").

The acting function $\mu$ is a {\GAP} function of the form

\){\kernttindent}actfun(<pnt>,<g>)

that returns the image $\mu(<pnt>,<g>)$ for a point $<pnt>\in<Omega>$ and a
group element $<g>\in<G>$.

Groups always acts from the right, that is
$\mu(\mu(<pnt>,<g>),<h>)=\mu(<pnt>,<gh>)$.

{\GAP} does not test whether an acting function `actfun' satisfies the
conditions for a group operation but silently assumes that is does.
(If it does not, results are unpredictable.)

The first section of this chapter, "About Group Actions", describes the
various ways how operations for group actions can be called.

Functions for several commonly used action are already built into {\GAP}.
These are listed in section~"Basic Actions".

The sections "The Permutation Image of an Action" and 
"Action of a group on itself" describe homomorphisms and mappings associated
to group actions as well as the permutation group image of an action.

The other sections then describe operations to compute orbits,
stabilizers, as well as
properties of actions.

Finally section~"External Sets" describes the concept of ``external sets''
which represent the concept of a *$G$-set* and underly the actions mechanism.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{About Group Actions}

\index{group actions!operations syntax}
The syntax which is used by the operations for group actions is quite
flexible. For example we can call the operation `OrbitsDomain' for the orbits
of the group <G> on the domain <Omega> in the following ways:

\)OrbitsDomain(<G>,<Omega>[,<actfun>])

The acting function <actfun> is optional. If it is not given, the built-in
action `OnPoints' (which defines an action via the caret operator `^') is
used as a default.

\)OrbitsDomain(<G>,<Omega>,<gens>,<acts>[,<actfun>])

This second version (of `OrbitsDomain') permits one to implement an action 
induced by a homomorphism:
If <H> acts on <Omega> via $\mu$ and $\varphi\colon G\to H$ is a
homomorphism, <G> acts on <Omega> via
$\mu'(\omega,g)=\mu(\omega,g^{\varphi})$:

Here <gens> must be a set of generators of <G> and <acts> the images of
<gens> under a homomorphism $\varphi\colon G\to H$.
<actfun> is the acting function for <H>, the call
to `ExampleActionFunction' implements the induced action of <G>.
Again, the acting function <actfun> is optional and `OnPoints' is used as a
default.

The advantage of this notation is that {\GAP} does not need to construct
this homomorphism $\varphi$ and the range group <H> as {\GAP} objects. (If a
small group <G> acts via complicated objects <acts> this otherwise could
lead to performance problems.)

{\GAP} does not test whether the mapping $<gens>\mapsto<acts>$
actually induces a homomorphism and the results are unpredictable if this is
not the case.

\)OrbitsDomain(<extset>) A

A third variant is to call the operation with an external set (which then
provides <G>, <Omega> and <actfun>. You will find more about external sets in
section~"External Sets".

For operations like `Stabilizer' of course the domain must be replaced by an
element of <Omega> which is to be acted on.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Basic Actions}

\index{group actions}
\index{actions}
\index{group operations}

{\GAP} already provides acting functions for the more common actions of a
group.  For built-in operations such as `Stabilizer' special methods are
available for many of these actions.

This section also shows how to implement different actions. (Note that every
action must be from the right.)

\Declaration{OnPoints}
\Declaration{OnRight}
\Declaration{OnLeftInverse}
\Declaration{OnSets}
\Declaration{OnTuples}
\Declaration{OnPairs}
\Declaration{OnSetsSets}
\Declaration{OnSetsDisjointSets}
\Declaration{OnSetsTuples}
\Declaration{OnTuplesSets}
\Declaration{OnTuplesTuples}
\beginexample
gap> g:=Group((1,2,3),(2,3,4));;
gap> Orbit(g,1,OnPoints);
[ 1, 2, 3, 4 ]
gap> Orbit(g,(),OnRight);
[ (), (1,2,3), (2,3,4), (1,3,2), (1,3)(2,4), (1,2)(3,4), (2,4,3), (1,4,2), 
  (1,4,3), (1,3,4), (1,2,4), (1,4)(2,3) ]
gap> Orbit(g,[1,2],OnPairs);
[ [ 1, 2 ], [ 2, 3 ], [ 1, 3 ], [ 3, 1 ], [ 3, 4 ], [ 2, 1 ], [ 1, 4 ], 
  [ 4, 1 ], [ 4, 2 ], [ 3, 2 ], [ 2, 4 ], [ 4, 3 ] ]
gap> Orbit(g,[1,2],OnSets);
[ [ 1, 2 ], [ 2, 3 ], [ 1, 3 ], [ 3, 4 ], [ 1, 4 ], [ 2, 4 ] ]
\endexample

\beginexample
gap> Orbit(g,[[1,2],[3,4]],OnSetsSets);
[ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 1, 4 ], [ 2, 3 ] ], [ [ 1, 3 ], [ 2, 4 ] ] ]
gap> Orbit(g,[[1,2],[3,4]],OnTuplesSets);
[ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 2, 3 ], [ 1, 4 ] ], [ [ 1, 3 ], [ 2, 4 ] ], 
  [ [ 3, 4 ], [ 1, 2 ] ], [ [ 1, 4 ], [ 2, 3 ] ], [ [ 2, 4 ], [ 1, 3 ] ] ]
gap> Orbit(g,[[1,2],[3,4]],OnSetsTuples);
[ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 1, 4 ], [ 2, 3 ] ], [ [ 1, 3 ], [ 4, 2 ] ], 
  [ [ 2, 4 ], [ 3, 1 ] ], [ [ 2, 1 ], [ 4, 3 ] ], [ [ 3, 2 ], [ 4, 1 ] ] ]
gap> Orbit(g,[[1,2],[3,4]],OnTuplesTuples);
[ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 2, 3 ], [ 1, 4 ] ], [ [ 1, 3 ], [ 4, 2 ] ], 
  [ [ 3, 1 ], [ 2, 4 ] ], [ [ 3, 4 ], [ 1, 2 ] ], [ [ 2, 1 ], [ 4, 3 ] ], 
  [ [ 1, 4 ], [ 2, 3 ] ], [ [ 4, 1 ], [ 3, 2 ] ], [ [ 4, 2 ], [ 1, 3 ] ], 
  [ [ 3, 2 ], [ 4, 1 ] ], [ [ 2, 4 ], [ 3, 1 ] ], [ [ 4, 3 ], [ 2, 1 ] ] ]
\endexample

\Declaration{OnLines}
\beginexample
gap> gl:=GL(2,5);;v:=[1,0]*Z(5)^0;
[ Z(5)^0, 0*Z(5) ]
gap> h:=Action(gl,Orbit(gl,v,OnLines),OnLines);
Group([ (2,3,5,6), (1,2,4)(3,6,5) ])
\endexample

\Declaration{OnIndeterminates}!{as a permutation action}

\>Permuted( <list>, <perm> )!{as a permutation action}

The following example demonstrates `Permuted' being used to implement a 
permutation action on a domain:

\beginexample
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" ] ]
\endexample

\Declaration{OnSubspacesByCanonicalBasis}

\bigskip

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

\)actfun(<omega>,<g>)

For example one could define the following function that acts on pairs of
polynomials via `OnIndeterminates':
\begintt
OnIndeterminatesPairs:=function(polypair,g)
  return [OnIndeterminates(polypair[1],g),
          OnIndeterminates(polypair[2],g)];
end;
\endtt

Note that this function *must* implement an action from the *right*. This is
not verified by {\GAP} and results are unpredicatble otherwise.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Orbits}

If <G> acts on <Omega> the set of all images of $\omega\in<Omega>$ under
elements of <G> is called the *orbit* of $\omega$. The set of orbits of <G>
is a partition of <Omega>.

Note that currently {\GAP} does *not* check whether a given point really
belongs to $\Omega$.
For example, consider the following example where the projective action
of a matrix group on a finite vector space shall be computed.

\beginexample
gap> Orbit( GL(2,3), [ -1, 0 ] * Z(3)^0, OnLines );
[ [ Z(3), 0*Z(3) ], [ Z(3)^0, 0*Z(3) ], [ Z(3)^0, Z(3) ], [ Z(3)^0, Z(3)^0 ], 
  [ 0*Z(3), Z(3)^0 ] ]
gap> Size( GL(2,3) ) / Length( last );
48/5
\endexample

The error is that `OnLines' (see~"OnLines") acts on the set of normed row
vectors (see~"NormedRowVectors") of the vector space in question,
but that the seed vector is itself not such a vector.

\Declaration{Orbit}
\beginexample
gap> g:=Group((1,3,2),(2,4,3));;
gap> Orbit(g,1);
[ 1, 3, 2, 4 ]
gap> Orbit(g,[1,2],OnSets);
[ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 3, 4 ], [ 2, 4 ] ]
\endexample
(See Section~"Basic Actions" for information about specific actions.)

\Declaration{Orbits}!{operation/attribute}
\Declaration{OrbitsDomain}
\beginexample
gap> g:=Group((1,3,2),(2,4,3));;
gap> Orbits(g,[1..5]);
[ [ 1, 3, 2, 4 ], [ 5 ] ]
gap> OrbitsDomain(g,Arrangements([1..4],3),OnTuples);
[ [ [ 1, 2, 3 ], [ 3, 1, 2 ], [ 1, 4, 2 ], [ 2, 3, 1 ], [ 2, 1, 4 ], 
      [ 3, 4, 1 ], [ 1, 3, 4 ], [ 4, 2, 1 ], [ 4, 1, 3 ], [ 2, 4, 3 ], 
      [ 3, 2, 4 ], [ 4, 3, 2 ] ], 
  [ [ 1, 2, 4 ], [ 3, 1, 4 ], [ 1, 4, 3 ], [ 2, 3, 4 ], [ 2, 1, 3 ], 
      [ 3, 4, 2 ], [ 1, 3, 2 ], [ 4, 2, 3 ], [ 4, 1, 2 ], [ 2, 4, 1 ], 
      [ 3, 2, 1 ], [ 4, 3, 1 ] ] ]
gap> OrbitsDomain(g,GF(2)^2,[(1,2,3),(1,4)(2,3)],
> [[[Z(2)^0,Z(2)^0],[Z(2)^0,0*Z(2)]],[[Z(2)^0,0*Z(2)],[0*Z(2),Z(2)^0]]]);
[ [ <an immutable GF2 vector of length 2> ], 
  [ <an immutable GF2 vector of length 2>, <an immutable GF2 vector of length 
        2>, <an immutable GF2 vector of length 2> ] ]
\endexample
(See Section~"Basic Actions" for information about specific actions.)

\Declaration{OrbitLength}
\Declaration{OrbitLengths}
\Declaration{OrbitLengthsDomain}
\beginexample
gap> g:=Group((1,3,2),(2,4,3));;
gap> OrbitLength(g,[1,2,3,4],OnTuples);
12
gap> OrbitLengths(g,Arrangements([1..4],4),OnTuples);
[ 12, 12 ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Stabilizers}

\index{point stabilizer}\index{set stabilizer}\index{tuple stabilizer}
The *Stabilizer* of an element $\omega$ is the set of all those $g\in G$
which fix $\omega$.


\Declaration{OrbitStabilizer}
\Declaration{Stabilizer}
\beginexample
gap> g:=Group((1,3,2),(2,4,3));;
gap> Stabilizer(g,4);
Group([ (1,3,2) ])
\endexample

The stabilizer of a set or tuple of points can be computed by specifying an
action of sets or tuples of points.
\beginexample
gap> Stabilizer(g,[1,2],OnSets);
Group([ (1,2)(3,4) ])
gap> Stabilizer(g,[1,2],OnTuples);
Group(())
gap> OrbitStabilizer(g,[1,2],OnSets);
rec( orbit := [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 3, 4 ], [ 2, 4 ] ], 
  stabilizer := Group([ (1,2)(3,4) ]) )
\endexample
(See Section~"Basic Actions" for information about specific actions.)

The standard methods for all these actions are an Orbit-Stabilizer
algorithm. For permutation groups backtrack algorithms are used. For
solvable groups an orbit-stabilizer algorithm for solvable groups, which
uses the fact that the orbits of a normal subgroup form a block system (see
\cite{SOGOS}) is used.

\Declaration{OrbitStabilizerAlgorithm}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Elements with Prescribed Images}

\index{transporter}
\Declaration{RepresentativeAction}
\beginexample
gap> g:=Group((1,3,2),(2,4,3));;
gap> RepresentativeAction(g,1,3);
(1,3)(2,4)
gap> RepresentativeAction(g,1,3,OnPoints);
(1,3)(2,4)
gap> RepresentativeAction(g,(1,2,3),(2,4,3));
(1,2,4)
gap> RepresentativeAction(g,(1,2,3),(2,3,4));
fail
gap> RepresentativeAction(g,Group((1,2,3)),Group((2,3,4)));
(1,2,4)
gap>  RepresentativeAction(g,[1,2,3],[1,2,4],OnSets);
(2,4,3)
gap>  RepresentativeAction(g,[1,2,3],[1,2,4],OnTuples);
fail
\endexample
(See Section~"Basic Actions" for information about specific actions.)

Again the standard method for `RepresentativeAction' is an orbit-stabilizer
algorithm, for permutation groups and standard actions a backtrack algorithm
is used.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The Permutation Image of an Action}

If $G$ acts on a domain <Omega>, an enumeration of <Omega> yields a
homomorphism of $G$ into the symmetric group on $\{1,\ldots,|<Omega>|\}$. In
{\GAP}, the enumeration of the domain <Omega> is provided by the
`Enumerator' of <Omega> (see~"Enumerator") which of course is <Omega> itself
if it is a list.

\Declaration{ActionHomomorphism}
(See Section~"Basic Actions" for information about specific actions.)
\beginexample
gap> g:=Group((1,2,3),(1,2));;
gap> hom:=ActionHomomorphism(g,Arrangements([1..4],3),OnTuples);
<action homomorphism>
gap> Image(hom);
Group([ (1,9,13)(2,10,14)(3,7,15)(4,8,16)(5,12,17)(6,11,18)(19,22,23)(20,21,
    24), (1,7)(2,8)(3,9)(4,10)(5,11)(6,12)(13,15)(14,16)(17,18)(19,21)(20,
    22)(23,24) ])
gap> Size(Range(hom));Size(Image(hom));
620448401733239439360000
6
gap> hom:=ActionHomomorphism(g,Arrangements([1..4],3),OnTuples,
> "surjective");;
gap> Size(Range(hom));
6
\endexample

When acting on a domain, the operation `PositionCanonical' is used to
determine the position of elements in the domain.  This can be used to act
on a domain given by a list of representatives for which `PositionCanonical'
is implemented, for example a `RightTransversal' (see "RightTransversal").

\Declaration{Action}
(See Section~"Basic Actions" for information about specific actions.)
\index{regular action}
The following code shows for example how to create the regular action of a
group:
\beginexample
gap> g:=Group((1,2,3),(1,2));;
gap> Action(g,AsList(g),OnRight);
Group([ (1,4,5)(2,3,6), (1,3)(2,4)(5,6) ])
\endexample

\Declaration{SparseActionHomomorphism}
\beginexample
gap> h:=Group(Z(3)*[[[1,1],[0,1]]]);
Group([ [ [ Z(3), Z(3) ], [ 0*Z(3), Z(3) ] ] ])
gap> hom:=ActionHomomorphism(h,GF(3)^2,OnRight);;
gap> Image(hom);
Group([ (2,3)(4,9,6,7,5,8) ])
gap> hom:=SparseActionHomomorphism(h,[Z(3)*[1,0]],OnRight);;
gap> Image(hom);
Group([ (1,2,3,4,5,6) ])
\endexample

For an action homomorphism, the operation `UnderlyingExternalSet'
(see~"UnderlyingExternalSet") will return the external set on <Omega> which
affords the action.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Action of a group on itself}

Of particular importance is the action of a group on its elements or cosets
of a subgroup. These actions can be obtained by using `ActionHomomorphism'
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:

\Declaration{FactorCosetAction}

\beginexample
gap> g:=Group((1,2,3,4,5),(1,2));;u:=SylowSubgroup(g,2);;Index(g,u);
15
gap> FactorCosetAction(g,u);
<action epimorphism>
gap> Range(last);
Group([ (1,9,13,10,4)(2,8,14,11,5)(3,7,15,12,6), 
  (1,7)(2,8)(3,9)(5,6)(10,11)(14,15) ])
\endexample

A special case is the regular action on all elements:
\Declaration{RegularActionHomomorphism}

\Declaration{AbelianSubfactorAction}
\beginexample
gap> g:=Group((1,8,10,7,3,5)(2,4,12,9,11,6),(1,9,5,6,3,10)(2,11,12,8,4,7));;
gap> c:=ChiefSeries(g);;List(c,Size);
[ 96, 48, 16, 4, 1 ]
gap> HasElementaryAbelianFactorGroup(c[3],c[4]);
true
gap> SetName(c[3],"my_group");;
gap> a:=AbelianSubfactorAction(g,c[3],c[4]);
[ [ (1,8,10,7,3,5)(2,4,12,9,11,6), (1,9,5,6,3,10)(2,11,12,8,4,7) ] -> 
    [ <an immutable 2x2 matrix over GF2>, <an immutable 2x2 matrix over GF2> ]
    , MappingByFunction( my_group, ( GF(2)^
    2 ), function( e ) ... end, function( r ) ... end ), 
  Pcgs([ (2,8,3,9)(4,10,5,11), (1,6,12,7)(4,10,5,11) ]) ]
gap> mat:=Image(a[1],g);
Group([ <an immutable 2x2 matrix over GF2>, 
  <an immutable 2x2 matrix over GF2> ])
gap> Size(mat);
3
gap> e:=PreImagesRepresentative(a[2],[Z(2),0*Z(2)]);
(2,8,3,9)(4,10,5,11)
gap> e in c[3];e in c[4];
true
false
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Permutations Induced by Elements and Cycles}

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.

\Declaration{Permutation}
\Declaration{PermutationCycle}
\beginexample
gap> Permutation([[Z(3),-Z(3)],[Z(3),0*Z(3)]],AsList(GF(3)^2));
(2,7,6)(3,4,8)
gap> Permutation((1,2,3)(4,5)(6,7),[4..7]);
(1,2)(3,4)
gap> PermutationCycle((1,2,3)(4,5)(6,7),[4..7],4);
(1,2)
\endexample
\Declaration{Cycle}
\Declaration{CycleLength}
\Declaration{Cycles}
\Declaration{CycleLengths}
\beginexample
gap> Cycle((1,2,3)(4,5)(6,7),[4..7],4);
[ 4, 5 ]
gap> CycleLength((1,2,3)(4,5)(6,7),[4..7],4);
2
gap> Cycles((1,2,3)(4,5)(6,7),[4..7]);
[ [ 4, 5 ], [ 6, 7 ] ]
gap> CycleLengths((1,2,3)(4,5)(6,7),[4..7]);
[ 2, 2 ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Tests for Actions}

\Declaration{IsTransitive}[oprt]!{for group actions}
\Declaration{Transitivity}[oprt]!{for group actions}
\beginexample
gap> g:=Group((1,3,2),(2,4,3));;
gap> IsTransitive(g,[1..5]);
false
gap> Transitivity(g,[1..4]);
2
\endexample

*Note:* For permutation groups, the syntax `IsTransitive(<g>)' is also
permitted and tests whether the group is transitive on the points moved by
it, that is the group $\langle (2,3,4),(2,3)\rangle$ is transitive (on 3
points).

\Declaration{RankAction}
\beginexample
gap> RankAction(g,Combinations([1..4],2),OnSets);
4
\endexample
\Declaration{IsSemiRegular}
\Declaration{IsRegular}
\beginexample
gap> IsSemiRegular(g,Arrangements([1..4],3),OnTuples);
true
gap> IsRegular(g,Arrangements([1..4],3),OnTuples);
false
\endexample
\Declaration{Earns}

\Declaration{IsPrimitive}
\beginexample
gap> IsPrimitive(g,Orbit(g,(1,2)(3,4)));
true
\endexample
%\declaration{IsFixpointFree}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Block Systems}

A *block system* (system of imprimitivity) for the action of <G> on <Omega>
is a partition of <Omega> which -- as a partition -- remains invariant under
the action of <G>.

\Declaration{Blocks}
\beginexample
gap> g:=TransitiveGroup(8,3);
E(8)=2[x]2[x]2
gap> Blocks(g,[1..8]);
[ [ 1, 8 ], [ 2, 3 ], [ 4, 5 ], [ 6, 7 ] ]
gap> Blocks(g,[1..8],[1,4]);
[ [ 1, 4 ], [ 2, 7 ], [ 3, 6 ], [ 5, 8 ] ]
\endexample
(See Section~"Basic Actions" for information about specific actions.)

\Declaration{MaximalBlocks}
\beginexample
gap> MaximalBlocks(g,[1..8]);
[ [ 1, 2, 3, 8 ], [ 4, 5, 6, 7 ] ]
\endexample

\Declaration{RepresentativesMinimalBlocks}
\beginexample
gap> RepresentativesMinimalBlocks(g,[1..8]);
[ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 1, 5 ], [ 1, 6 ], [ 1, 7 ], [ 1, 8 ] ]
\endexample

\Declaration{AllBlocks}
\beginexample
gap> AllBlocks(g);
[ [ 1, 8 ], [ 1, 2, 3, 8 ], [ 1, 4, 5, 8 ], [ 1, 6, 7, 8 ], [ 1, 3 ], 
  [ 1, 3, 5, 7 ], [ 1, 3, 4, 6 ], [ 1, 5 ], [ 1, 2, 5, 6 ], [ 1, 2 ], 
  [ 1, 2, 4, 7 ], [ 1, 4 ], [ 1, 7 ], [ 1, 6 ] ]
\endexample

The stabilizer of a block can be computed via the action
`OnSets' (see~"OnSets"):
\beginexample
gap> Stabilizer(g,[1,8],OnSets);
Group([ (1,8)(2,3)(4,5)(6,7) ])
\endexample

If <bs> is a partition of <omega>, given as a set of sets, the stabilizer
under the action `OnSetsDisjointSets' (see~"OnSetsDisjointSets") returns the
largest subgroup which preserves <bs> as a block system.
\beginexample
gap> g:=Group((1,2,3,4,5,6,7,8),(1,2));;
gap> bs:=[[1,2,3,4],[5,6,7,8]];;
gap> Stabilizer(g,bs,OnSetsDisjointSets);
Group([ (6,7), (5,6), (5,8), (2,3), (3,4)(5,7), (1,4), (1,5,4,8)(2,6,3,7) ])
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{External Sets}

\atindex{G-sets}{@$G$-sets}
When considering group actions, sometimes the concept of a *$G$-set* is
used. This is the set <Omega> endowed with an action of $G$. The elements
of the $G$-set are the same as those of <Omega>, however concepts like
equality and equivalence of $G$-sets do not only consider the underlying
domain <Omega> but the group action as well.

This concept is implemented in {\GAP} via *external sets*.
\Declaration{IsExternalSet}

\Declaration{ExternalSet}
\beginexample
gap> g:=Group((1,2,3),(2,3,4));;
gap> e:=ExternalSet(g,[1..4]);
<xset:[ 1, 2, 3, 4 ]>
gap> e:=ExternalSet(g,g,OnRight);
<xset:<enumerator of perm group>>
gap> Orbits(e);
[ [ (), (1,2)(3,4), (1,3)(2,4), (1,4)(2,3), (2,4,3), (1,4,2), (1,2,3), 
      (1,3,4), (2,3,4), (1,3,2), (1,4,3), (1,2,4) ] ]
\endexample

The following three attributes of an external set hold its constituents.
\Declaration{ActingDomain}
\Declaration{FunctionAction}
\Declaration{HomeEnumerator}
\beginexample
gap> ActingDomain(e);
Group([ (1,2,3), (2,3,4) ])
gap> FunctionAction(e)=OnRight;
true
gap> HomeEnumerator(e);
<enumerator of perm group>
\endexample

Most operations for actions are applicable as an attribute for an external
set.

\Declaration{IsExternalSubset}
The most prominent external subsets are orbits:
\Declaration{ExternalSubset}
\Declaration{IsExternalOrbit}
\Declaration{ExternalOrbit}
\beginexample
gap> e:=ExternalOrbit(g,g,(1,2,3));
(1,2,3)^G
\endexample

Many subsets of a group, such as conjugacy classes or cosets
(see~"ConjugacyClass" and "RightCoset") are implemented as external orbits.

\Declaration{StabilizerOfExternalSet}
\beginexample
gap> Representative(e);
(1,2,3)
gap> StabilizerOfExternalSet(e);
Group([ (1,2,3) ])
\endexample

\Declaration{ExternalOrbits}
\beginexample
gap> ExternalOrbits(g,AsList(g));
[ ()^G, (2,3,4)^G, (2,4,3)^G, (1,2)(3,4)^G ]
\endexample

\Declaration{ExternalOrbitsStabilizers}
\beginexample
gap> e:=ExternalOrbitsStabilizers(g,AsList(g));
[ ()^G, (2,3,4)^G, (2,4,3)^G, (1,2)(3,4)^G ]
gap> HasStabilizerOfExternalSet(e[3]);
true
gap> StabilizerOfExternalSet(e[3]);
Group([ (2,4,3) ])
\endexample

\Declaration{CanonicalRepresentativeOfExternalSet}
\Declaration{CanonicalRepresentativeDeterminatorOfExternalSet}
\Declaration{ActorOfExternalSet}
\beginexample
gap> u:=Subgroup(g,[(1,2,3)]);;
gap> e:=RightCoset(u,(1,2)(3,4));;
gap> CanonicalRepresentativeOfExternalSet(e);
(2,4,3)
gap> ActorOfExternalSet(e);
(1,3,2)
gap> FunctionAction(e)((1,2)(3,4),last);
(2,4,3)
\endexample

External sets also are implicitly underlying action homomorphisms:

\Declaration{UnderlyingExternalSet}
\beginexample
gap> g:=Group((1,2,3),(1,2));;
gap> hom:=ActionHomomorphism(g,Arrangements([1..4],3),OnTuples);;
gap> s:=UnderlyingExternalSet(hom);
<xset:[[ 1, 2, 3 ],[ 1, 2, 4 ],[ 1, 3, 2 ],[ 1, 3, 4 ],[ 1, 4, 2 ],
[ 1, 4, 3 ],[ 2, 1, 3 ],[ 2, 1, 4 ],[ 2, 3, 1 ],[ 2, 3, 4 ],[ 2, 4, 1 ],
[ 2, 4, 3 ],[ 3, 1, 2 ],[ 3, 1, 4 ],[ 3, 2, 1 ], ...]>
gap> Print(s,"\n");
[ [ 1, 2, 3 ], [ 1, 2, 4 ], [ 1, 3, 2 ], [ 1, 3, 4 ], [ 1, 4, 2 ], 
  [ 1, 4, 3 ], [ 2, 1, 3 ], [ 2, 1, 4 ], [ 2, 3, 1 ], [ 2, 3, 4 ], 
  [ 2, 4, 1 ], [ 2, 4, 3 ], [ 3, 1, 2 ], [ 3, 1, 4 ], [ 3, 2, 1 ], 
  [ 3, 2, 4 ], [ 3, 4, 1 ], [ 3, 4, 2 ], [ 4, 1, 2 ], [ 4, 1, 3 ], 
  [ 4, 2, 1 ], [ 4, 2, 3 ], [ 4, 3, 1 ], [ 4, 3, 2 ] ]
\endexample

\Declaration{SurjectiveActionHomomorphismAttr}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E