%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  matreps.tex           GAP documentation                  Bettina Eick
%W                                                          Werner Nickel
%%
%H  $Id: matreps.tex,v 1.6 2007/06/08 16:48:49 werner Exp $
%%

\Chapter{Matrix Representations}

This chapter describes functions which compute with matrix
representations for pcp-groups.  So far the routines in this package
are only able to compute matrix representations for torsion-free
nilpotent groups.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Unitriangular matrix groups}

\>UnitriangularMatrixRepresentation( G )

computes a faithful representation of a torsion-free nilpotent group
<G> as unipotent lowertriangular matrices over the integers.  The
pc-presentation for <G> must not contain any power relations.  The
algorithm is described in \cite{dGN02}.

\>IsMatrixRepresentation( <G>, <matrices> )

checks if the map defined by maping the i-th generator of the
pcp-group <G> to the i-th matrix of <matrices> defines a homomorphism.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Upper unitriangular matrix groups}

We call a matrix upper unitriangular if it is an upper triangular
matrix with ones on the main diagonal.  The weight of an upper
unitriangular matrix is the number of diagonals above the main
diagonal that contain zeroes only.  

The subgroup of all upper unitriangular matrices of $GL(n,\Z)$ is
torsion-free nilpotent.  The k-th term of its lower central series is
the set of all matrices of weight $k-1$.  The $\Z$-rank of the k-th
term of the lower central series modulo the $(k+1)$-th term is $n-k$.

\>IsomorphismUpperUnitriMatGroupPcpGroup( <G> )

takes a group <G> generated by upper unitriangular matrices over the
integers and computes a polycylic presentation for the group.  The
function returns an isomorphism from the matrix group to the pcp
group.  Note that a group generated by upper unitriangular matrices is
necessarily torsion-free nilpotent.

\>SiftUpperUnitriMatGroup( <G> )
 
takes a group <G> generated by upper unitriangular matrices over the
integers and returns a recursive data structure <L> with the following
properties: <L> contains a polycyclic generating sequence for <G>,
using <L> one can decide if a given upper unitriangular matrix is
contained in <G>, a given element of <G> can be written as a word in
the polycyclic generating sequence.  <L> is a representation of a
chain of subgroups of <G> refining the lower centrals series of <G>..
It contains for each subgroup in the chain a minimal generating set.

\>RanksLevels( <L> )

takes the data structure returned by `SiftUpperUnitriMat' and prints
the \Z-rank of each the subgroup in <L>.

\>MakeNewLevel( <m> )

creates one level of the data structure returned by
`SiftUpperUnitriMat' and initialises it with weight <m>.

\>SiftUpperUnitriMat( gens, level, M )

takes the generators <gens> of an upper  unitriangular group, the data 
structure returned <level> by `SiftUpperUnitriMat' and another upper
unitriangular matrix <M>.  It sift <M> through <level> and adds <M> at
the appropriate place if <M> is not contained in the subgroup
represented by <level>. 

The function `SiftUpperUnitriMatGroup' illustrates the use of
`SiftUpperUnitriMat'.
\beginexample
InstallGlobalFunction( "SiftUpperUnitriMatGroup", function( G )
    local   firstlevel,  g;

    firstlevel := MakeNewLevel( 0 );
    for g in GeneratorsOfGroup(G) do
        SiftUpperUnitriMat( GeneratorsOfGroup(G), firstlevel, g );
    od;
    return firstlevel;
end );
\endexample

\>DecomposeUpperUnitriMat( <level>, <M> )

takes the data structure <level> returned by `SiftUpperUnitriMatGroup'
and a upper unitriangular matrix <M> and decomposes <M> into a word in
the polycyclic generating sequence of <level>.