<Chapter Label="Functionality of the FGA package">
<Heading>Functionality of the FGA package</Heading>

<Index>Functionality of the FGA package</Index>

This chapter describes methods available from the &FGA; package.
<P/>
In the following, let <A>f</A> be a free group created by <C>FreeGroup(<A>n</A>)</C>,
and let <A>u</A>, <A>u1</A> and <A>u2</A> be finitely generated subgroups of <A>f</A>
created by <C>Group</C> or <C>Subgroup</C>, or computed from some other subgroup
of <A>f</A>.  Let <A>elm</A> be an element of <A>f</A>.
<P/>
For example:
<P/>
<Example><![CDATA[
gap> f := FreeGroup( 2 );                                             
<free group on the generators [ f1, f2 ]>
gap> u := Group( f.1^2, f.2^2, f.1*f.2 );
Group([ f1^2, f2^2, f1*f2 ])
gap> u1 := Subgroup( u, [f.1^2, f.1^4*f.2^6] );
Group([ f1^2, f1^4*f2^6 ])
gap> elm := f.1;
f1
gap> u2 := Normalizer( u, elm );
Group([ f1^2 ])
]]></Example>
<P/>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="New operations for free groups">
<Heading>New operations for free groups</Heading>

These new operations are available for finitely generated subgroups of
free groups:

<ManSection>
<Attr Name="FreeGeneratorsOfGroup" Arg="u"/>
<Description>
returns a list of free generators of the finitely generated subgroup
<A>u</A> of a free group.
<P/>
The elements in this list form an N-reduced set.  In addition to
being a free (and thus minimal) generating set for <A>u</A>, this means
that whenever <A>v1</A>, <A>v2</A> and <A>v3</A> are elements or inverses of elements
of this list, then
<P/>
<List>
<Item>
    <M><A>v1</A><A>v2</A>\neq1</M> implies <M>|<A>v1</A><A>v2</A>|\geq\max(|<A>v1</A>|, |<A>v2</A>|)</M>, and
</Item>
<Item>
    <M><A>v1</A><A>v2</A>\neq1</M> and <M><A>v2</A><A>v3</A>\neq1</M> implies
    <M>|<A>v1</A><A>v2</A><A>v3</A>| > |<A>v1</A>| - |<A>v2</A>| + |<A>v3</A>|</M>
</Item>
</List>
<P/>
hold, where <M>|.|</M> denotes the word length.
</Description>
</ManSection>

<ManSection>
<Attr Name="RankOfFreeGroup" Arg="u"/>
<Oper Name="Rank" Arg="u"/>
<Description>
returns the rank of the finitely generated subgroup <A>u</A> of a free
group.
</Description>
</ManSection>

<ManSection>
<Oper Name="CyclicallyReducedWord" Arg="elm"/>
<Description>
returns the cyclically reduced form of <A>elm</A>.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Method installations">
<Heading>Method installations</Heading>

This section lists operations that are already known to &GAP;.
&FGA; installs new methods for them so that they can also be used
with free groups.
In cases where &FGA; installs methods that are usually only used
internally, user functions are shown instead.
<P/>

<ManSection>
<Oper Name="Normalizer" Arg="u1, u2"/>
<Oper Name="Normalizer" Arg="u, elm"/>
<Description>
The first variant returns the normalizer of the finitely generated
subgroup <A>u2</A> in <A>u1</A>.
<P/>
The second variant returns the normalizer of <M>\langle <A>elm</A> \rangle</M>
in the finitely generated subgroup <A>u</A> (see <Ref BookName="ref" Oper="Normalizer"/> in the
Reference Manual).
</Description>
</ManSection>

<ManSection>
<Oper Name="RepresentativeAction" Arg="u, d, e"/>
<Oper Name="IsConjugate" Arg="u, d, e"/>
<Description>
<C>RepresentativeAction</C> returns an element <M> <A>r</A> \in <A>u</A> </M>,
where <A>u</A> is a finitely generated subgroup of a free group, such
that <M><A>d</A>^{<A>r</A>}=<A>e</A></M>, or fail, if no such <A>r</A> exists.  <A>d</A> and <A>e</A> may
be elements or subgroups of <A>u</A>.
<P/>
<C>IsConjugate</C> returns a boolean indicating whether such an element <A>r</A>
exists.
</Description>
</ManSection>

<ManSection>
<Oper Name="Centralizer" Arg="u, u2"/>
<Oper Name="Centralizer" Arg="u, elm"/>
<Description>
returns the centralizer of <A>u2</A> or <A>elm</A> in the finitely generated
subgroup <A>u</A> of a free group.
</Description>
</ManSection>

<ManSection>
<Oper Name="Index" Arg="u1, u2"/>
<Oper Name="IndexNC" Arg="u1, u2"/>
<Description>
return the index of <A>u2</A> in <A>u1</A>, where <A>u1</A> and <A>u2</A> are finitely
generated subgroups of a free group.  The first variant returns
fail if <A>u2</A> is not a subgroup of <A>u1</A>, the second may return
anything in this case.
</Description>
</ManSection>

<ManSection>
<Func Name="Intersection" Arg="u1, u2 \dots"/>
<Description>
returns the intersection of <A>u1</A> and <A>u2</A>, where <A>u1</A> and <A>u2</A> are
finitely generated subgroups of a free group.
</Description>
</ManSection>

<ManSection>
<Meth Name="\in" Arg="elm, u"/>
<Description>
tests whether <A>elm</A> is contained in the finitely generated subgroup
<A>u</A> of a free group.
</Description>
</ManSection>

<ManSection>
<Func Name="IsSubgroup" Arg="u1, u2"/>
<Description>
tests whether <A>u2</A> is a subgroup of <A>u1</A>, where <A>u1</A> and <A>u2</A> are finitely
generated subgroups of a free group.
</Description>
</ManSection>

<ManSection>
<Meth Name="\=" Arg="u1, u2"/>
<Description>
test whether the two finitely generated subgroups <A>u1</A> and <A>u2</A> of a
free group are equal.
</Description>
</ManSection>

<ManSection>
<Attr Name="MinimalGeneratingSet" Arg="u"/>
<Attr Name="SmallGeneratingSet" Arg="u"/>
<Attr Name="GeneratorsOfGroup" Arg="u"/>
<Description>
return generating sets for the finitely generated subgroup <A>u</A> of a
free group.  <C>MinimalGeneratingSet</C> and <C>SmallGeneratingSet</C> return
the same free generators as <C>FreeGeneratorsOfGroup</C>, which are in
fact a minimal generating set.  <C>GeneratorsOfGroup</C> also returns these
generators, if no other generators were stored at creation time.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Constructive membership test">  
<Heading>Constructive membership test</Heading>

It is not only possible to test whether an element is in a finitely
generated subgroup of free group, this can also be done
constructively.  The idiomatic way to do so is by using a
homomorphism.
<P/>
Here is an example that computes how to write <C>f.1^2</C> in the
generators <C>a=f1^2*f2^2</C> and <C>b=f.1^2*f.2</C>, checks the result, and
then tries to write <C>f.1</C> in the same generators:
<P/>
<Example><![CDATA[
gap> f := FreeGroup( 2 );
<free group on the generators [ f1, f2 ]>
gap> ua := f.1^2*f.2^2;; ub := f.1^2*f.2;;
gap> u := Group( ua, ub );;
gap> g := FreeGroup( "a", "b" );;
gap> hom := GroupHomomorphismByImages( g, u,
>             GeneratorsOfGroup(g),
>             GeneratorsOfGroup(u) );
[ a, b ] -> [ f1^2*f2^2, f1^2*f2 ]
gap> # how can f.1^2 be expressed?
gap> PreImagesRepresentative( hom, f.1^2 );
b*a^-1*b
gap> last ^ hom; # check this
f1^2
gap> ub * ua^-1 * ub; # another check
f1^2
gap> PreImagesRepresentative( hom, f.1 ); # try f.1
fail
gap> f.1 in u;
false
]]></Example>
<P/>
There are also lower level operations to get the same results.
<P/>

<ManSection>
<Oper Name="AsWordLetterRepInGenerators" Arg="elm, u"/>
<Oper Name="AsWordLetterRepInFreeGenerators" Arg="elm, u"/>
<Description>
return a letter representation
(see Section&nbsp;<Ref BookName="ref" Sect="Representations for Associative Words"/> in the &GAP;
Reference Manual)
of the given <A>elm</A> relative to the generators the group was created
with or the free generators as returned by <C>FreeGeneratorsOfGroup</C>.
<P/>
Continuing the above example:
<P/>
<Example><![CDATA[
gap> AsWordLetterRepInGenerators( f.1^2, u );    
[ 2, -1, 2 ]
gap> AsWordLetterRepInFreeGenerators( f.1^2, u );
[ 2 ]
]]></Example>
<P/>
This means: to get <C>f.1^2</C>, multiply the second of the given generators
with the inverse of the first and again with the second; or just take
the second free generator.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Automorphism groups of free groups">
<Heading>Automorphism groups of free groups</Heading>

The &FGA; package knows presentations of the automorphism groups of free
groups. It also allows to express an automorphism as word in the
generators of these presentations.
This sections repeats the &GAP; standard methods to do so and shows
functions to obtain the generating automorphisms.

<ManSection>
<Attr Name="AutomorphismGroup" Arg="u"/>
<Description>
returns the automorphism group of the finitely generated subgroup <A>u</A>
of a free group.
<P/>
Only a few methods will work with this group. But there is a way to
obtain an isomorphic finitely presented group:
</Description>
</ManSection>

<ManSection>
<Attr Name="IsomorphismFpGroup" Arg="group"/>
<Description>
returns an isomorphism of <A>group</A> to a finitely presented group.  
For automorphism groups of free groups, the &FGA; package implements
the presentations of <Cite Key="Neumann33"/>.
The finitely presented group itself can then be obtained with the
command <C>Range</C>.
<P/>
Here is an example:
<P/>
<Example><![CDATA[
gap> f := FreeGroup( 2 );;
gap> a := AutomorphismGroup( f );;
gap> iso := IsomorphismFpGroup( a );;
gap> Range( iso );
<fp group on the generators [ O, P, U ]>
]]></Example>
<P/>
To express an automorphism as word in the generators of the
presentation, just apply the isomorphism obtained from
<C>IsomorphismFpGroup</C>.
<P/>
<Example><![CDATA[
gap> aut := GroupHomomorphismByImages( f, f,
>              GeneratorsOfGroup( f ), [ f.1^f.2, f.1*f.2 ] );
[ f1, f2 ] -> [ f2^-1*f1*f2, f1*f2 ]
gap> ImageElm( iso, aut );
O^2*U*O*P^-1*U
]]></Example>
<P/>
It is also possible to use <C>aut^iso</C> or <C>Image( iso, aut )</C>.
Using <C>Image</C> will perform additional checks on the arguments.
</Description>
</ManSection>

The &FGA; package provides a simpler way to create endomorphisms:
<P/>
<ManSection>
<Func Name="FreeGroupEndomorphismByImages" Arg="g, imgs"/>
<Description>
returns the endomorphism that maps the free generators of the finitely
generated subgroup <A>g</A> of a free group to the elements listed in <A>imgs</A>.
You may then apply <C>IsBijective</C> to check whether it is an
automorphism.
</Description>
</ManSection>

The following functions return automorphisms that correspond to the
generators in the presentation:
<P/>
<ManSection>
<Func Name="FreeGroupAutomorphismsGeneratorO" Arg="group"/>
<Func Name="FreeGroupAutomorphismsGeneratorP" Arg="group"/>
<Func Name="FreeGroupAutomorphismsGeneratorU" Arg="group"/>
<Func Name="FreeGroupAutomorphismsGeneratorS" Arg="group"/>
<Func Name="FreeGroupAutomorphismsGeneratorT" Arg="group"/>
<Func Name="FreeGroupAutomorphismsGeneratorQ" Arg="group"/>
<Func Name="FreeGroupAutomorphismsGeneratorR" Arg="group"/>
<Description>
return the automorphism which maps the free generators 
[<M> x_1, x_2, \dots, x_n </M>] of <A>group</A> to
<List>
<Mark>O:</Mark>
<Item>
 [<M> x_1^{-1}, x_2, \dots, x_n </M>]                      (<M>n\ge1</M>)
  
</Item>
<Mark>P:</Mark>
<Item>
 [<M> x_2, x_1, x_3, \dots, x_n </M>]                      (<M>n\ge2</M>)
  
</Item>
<Mark>U:</Mark>
<Item>
 [<M> x_1x_2, x_2, x_3, \dots, x_n </M>]                   (<M>n\ge2</M>)
  
</Item>
<Mark>S:</Mark>
<Item>
 [<M> x_2^{-1}, x_3^{-1}, \dots, x_n^{-1}, x_1^{-1} </M>]  (<M>n\ge1</M>)
  
</Item>
<Mark>T:</Mark>
<Item>
 [<M> x_2, x_1^{-1}, x_3, \dots, x_n </M>]                 (<M>n\ge2</M>)
  
</Item>
<Mark>Q:</Mark>
<Item>
 [<M> x_2, x_3, \dots, x_n, x_1 </M>]                      (<M>n\ge2</M>)
  
</Item>
<Mark>R:</Mark>
<Item>
 [<M> x_2^{-1}, x_1, x_3, x_4, \dots,
             x_{n-2}, x_nx_{n-1}^{-1}, x_{n-1}^{-1} </M>]           (<M>n\ge4</M>)
</Item>
</List>
</Description>
</ManSection>

</Section>
</Chapter>
