%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  util.tex                   XMOD documentation               Chris Wensley
%W                                                                & Murat Alp
%%
%H  $Id: util.tex,v 2.006 2004/09/06 gap Exp $
%%
%Y  Copyright (C) 1999,2001 University of St. Andrews, North Haugh,
%Y                          St. Andrews, Fife KY16 9SS, Scotland
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Utility functions}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

By a utility function we mean a {\GAP} function which is

\beginlist
\item{$\bullet$}
needed by other functions in this package,
\item{$\bullet$}
not (as far as we know) provided by the standard {\GAP} library,
\item{$\bullet$}
more suitable for inclusion in the main library than in this package.
\endlist

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Inclusion and Restriction Mappings}

\> InclusionMappingGroups( <G>, <H> ) O
\> RestrictionMappingGroups( <hom>, <src>, <rng> ) O
\> MappingToOne( <G>, <H> ) O

The first set of utilities concerns inclusion and restriction mappings.
Restriction may apply to both the source and the range of the map.
The map `incd8' is the inclusion of `d8' in `d16' used in Section 3.3.

\beginexample
gap> Print( incd8, "\n" );
[ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ] ->
[ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ]
gap> imd8 := Image( incd8 );;
gap> resd8 := RestrictionMappingGroups( incd8, c4, imd8 );;
gap> Source( res8 );  Range( res8 );
c4
Group([ (11,13,15,17)(12,14,16,18), (11,18)(12,17)(13,16)(14,15) ])
gap> MappingToOne( c4, imd8 );
[ (11,13,15,17)(12,14,16,18) ] -> [ () ]
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Endomorphism Classes and Automorphisms}

\> EndomorphismClasses( <grp>, <case> ) F
\> EndoClassNaturalHom( <class> ) A
\> EndoClassIsomorphism( <class> ) A
\> EndoClassConjugators( <class> ) A
\> AutoGroup( <class> )!{of endomorphism class}  A

The monoid of endomorphisms of a group is used when calculating
the monoid of derivations of a crossed module and when determining 
all the cat1-structures on a group.

An endomorphism $\epsilon$ of $R$ with image $H'$ is determined by
\beginlist
\item{$\bullet$}
a normal subgroup $N$ of $R$ and a permutation representation
$\theta : R/N \to Q$ of the quotient, giving a projection
$\theta \circ \nu : R \to Q$, where $\nu : R \to R/N$
is the natural homomorphism;
\item{$\bullet$}
an automorphism $\alpha$ of $Q$;
\item{$\bullet$}
a subgroup $H'$ in a conjugacy class $[H]$ of subgroups of $R$ 
isomorphic to $Q$ having representative $H$, an isomorphism 
$\phi : Q \cong H$, and a conjugating element $c \in R$
such that $H^c = H'$.
\endlist

Then $\epsilon$ takes values
$$
\epsilon r ~=~ (\phi\alpha\theta\nu\,r)^c~.
$$
Endomorphisms are placed in the same class if they have the same
choice of $N$ and $[H]$,
and so the number of endomorphisms is
$$
|{\rm End}(R)| ~=~ \sum_{{\rm classes}} |{\rm Aut}(Q)|.|[H]|~.
$$

The function `EndomorphismClasses( <grp>, <case> )' 
may be called in three ways:
\beginlist
\item{$\bullet$}
case 1 includes automorphisms and the zero map,
\item{$\bullet$}
case 2 excludes automorphisms and the zero map,
\item{$\bullet$}
case 3 is when `N' intersects `H'  trivially.
\endlist

\beginexample
gap> end8 := EndomorphismClasses( d8, 1 );;
gap> Length( end8 );
13
gap> e4 := end8[4];
<enumerator>
gap> EndoClassNaturalHom( e4 );
GroupHomomorphismByImages( d8, Group( [ f1 ] ),
[ (11,13,15,17)(12,14,16,18), (12,18)(13,17)(14,16) ], [ f1, f1 ] )
gap> EndoClassIsomorphism( e4 );
Pcgs([ f1 ]) -> [ (11,13)(14,18)(15,17) ]
gap> EndoClassConjugators( e4 );
[ (), (12,18)(13,17)(14,16) ]
gap> AutoGroup( e4 );
Group( [ Pcgs([ f1 ]) -> [ f1 ] ] )
gap> L := List( end8, e -> Length(EndoClassConjugators(e)) * Size(AutoGroup(e)) );
[ 8, 1, 2, 2, 1, 2, 2, 1, 2, 2, 6, 6, 1 ]
gap> Sum( L );
36
\endexample



\> InnerAutomorphismsByNormalSubgroup( <G>, <N> ) O
\> IsGroupOfAutomorphisms( <A> ) P

Inner automorphisms of a group `G' by the elements of a normal subgroup `N'
are calculated with the first of these functions, usually with `G' = `N'.

\beginexample
gap> autd8 := AutomorphismGroup( d8 );;
gap> innd8 := InnerAutomorphismsByNormalSubgroup( d8, d8 );;
gap> GeneratorsOfGroup( innd8 );
[ InnerAutomorphism( d8, (11,13,15,17)(12,14,16,18) ),
  InnerAutomorphism( d8, (12,18)(13,17)(14,16) ) ]
gap> IsGroupOfAutomorphisms( innd8 );
true 
\endexample



%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Abelian Modules}

\> IsAbelianModule( <obj> ) P
\> AbelianModuleGroup( <obj> ) A
\> AbelianModuleAction( <obj> ) A
\> AbelianModuleObject( <grp>, <act> ) O

An abelian module is an abelian group together with a group action.
These are used by the crossed module constructor
`XModByAbelianModule'.

\beginexample
gap> x := (6,7)(8,9);;  y := (6,8)(7,9);;  z := (6,9)(7,8);;
gap> k4 := Group( x, y );  SetName( k4, "k4" );
gap> s3 := Group( (1,2), (2,3) );;  SetName( s3, "s3" );
gap> alpha := GroupHomomorphismByImages( k4, k4, [x,y], [y,x] );
gap> beta := GroupHomomorphismByImages( k4, k4, [x,y], [x,z] );
gap> aut := Group( alpha, beta );
gap> act := GroupHomomorphismByImages( s3, aut, [(1,2),(2,3)], [alpha,beta] );
gap> abmod := AbelianModuleObject( k4, act );
<enumerator>
gap> Xabmod := XModByAbelianModule( abmod );
[k4->s3]
\endexample

The resulting `Xabmod' is isomorphic to the output from 
`XModByAutomorphismGroup( k4 );'.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Distinct and Common Representatives}

\> DistinctRepresentatives( <list> ) O
\> CommonRepresentatives( <list1>, <list2> ) O
\> CommonTransversal( <grp>, <subgrp> ) O
\> IsCommonTransversal( <grp>, <subgrp>, <list> ) O

The final set of utilities deal with lists of subsets of $[1 \ldots n]$
and construct systems of distinct and common representatives using
simple, non-recursive, combinatorial algorithms.

When $L$ is a set of $n$ subsets of $[1 \ldots n]$ 
and the Hall condition is satisfied
(the union of any $k$ subsets has at least $k$ elements),
a set of distinct representatives exists.

When $J,K$ are both lists of $n$ sets, the function `CommonRepresentatives' 
returns two lists: the set of representatives, 
and a permutation of the subsets of the second list.
It may also be used to provide a common transversal
for sets of left and right cosets of a subgroup $H$ of a group $G$,
although a greedy algorithm is usually quicker.

\beginexample
gap> J := [ [1,2,3], [3,4], [3,4], [1,2,4] ];;
gap> DistinctRepresentatives( J );
[ 1, 3, 4, 2 ]
gap> K := [ [3,4], [1,2], [2,3], [2,3,4] ];;
gap> CommonRepresentatives( J, K );
[ [ 3, 3, 3, 1 ], [ 1, 3, 4, 2 ] ]
gap> CommonTransversal( d16, c4 );
[ (), (12,18)(13,17)(14,16), (11,12,13,14,15,16,17,18),
  (11,12)(13,18)(14,17)(15,16) ]
gap> IsCommonTransversal( d16, c4, [ (), c, d, c*d ] );
true
\endexample

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