%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Examples}

\atindex{Nilmat package}{@Nilmat package}

In this chapter we give some examples of computing with the Package
\package{Nilmat}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Constructing some nilpotent matrix groups}

\beginexample
gap> g1 := MaximalAbsolutelyIrreducibleNilpotentMatGroup(52,3,3);
<matrix group with 7 generators>
\endexample

The group `g1' is a subgroup of $GL(52,3^3)$ generated by 7 matrices.

\beginexample
gap> g2 := MaximalAbsolutelyIrreducibleNilpotentMatGroup(180,11,2);
<matrix group with 41 generators>
\endexample

The group `g2' is a subgroup of $GL(180,11^2)$ generated by 41 matrices.

\beginexample
gap> MaximalAbsolutelyIrreducibleNilpotentMatGroup(210,2,10);
fail
\endexample

In this third example, absolutely irreducible nilpotent subgroups of
$GL(210,2^{10})$ do not exist, because the degree of the matrices
and the field size are both even.

\beginexample
gap> g3 := MonomialNilpotentMatGroup(450);
<matrix group with 24 generators>
\endexample

Here `g3' is a monomial nilpotent subgroup of $GL(450,\Q)$.

\beginexample
gap> g4 := ReducibleNilpotentReducibleMatGroup(3,180,11,2);
<matrix group with 82 generators>
\endexample

Here $`g4' \< GL(540,11^2)$ is the Kronecker product of a
unipotent subgroup of $GL(3,11^2)$ and the group `g2'.

\beginexample
gap> g5 := ReducibleNilpotentMatGroup(7,36);
<matrix group with 72 generators>
\endexample

Here $`g5' \< GL(252, \Q)$ is a reducible nilpotent group constructed
as the Kronecker product of a unipotent subgroup of $GL(7,\Q)$ with
`MonomialNilpotentMatGroup(36)'.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Testing nilpotency and other functions}

We now illustrate use of the functions
`IsNilpotentMatGroup',
`SylowSubgroupsOfNilpotentFFMatGroup',
`IsFiniteNilpotentMatGroup',
`SizeOfNilpotentMatGroup', and
`IsCompletelyReducibleNilpotentMatGroup'.

\beginexample
gap> IsNilpotentMatGroup(GL(200,Rationals));
false

gap> IsNilpotentMatGroup(GL(150,11^3));
false

gap> g6 := MaximalAbsolutelyIrreducibleNilpotentMatGroup(127,2,7);
<matrix group with 3 generators>
gap> IsNilpotentMatGroup(g6);
true

gap> g7 := MonomialNilpotentMatGroup(350);
<matrix group with 6 generators>
gap> IsNilpotentMatGroup(g7);
true
gap> IsFiniteNilpotentMatGroup(g7);
true

gap> g8 := ReducibleNilpotentMatGroup(6,35);
<matrix group with 5 generators>
gap> IsNilpotentMatGroup(g8);
true
gap> IsFiniteNilpotentMatGroup(g8);
false

gap> g9 := ReducibleNilpotentMatGroup(2,36,5,2);
<matrix group with 21 generators>
gap> SylowSubgroupsOfNilpotentFFMatGroup(g9);
[ <matrix group with 5 generators>, <matrix group with 6
generators>, <matrix group with 1 generators> ]
gap> IsCompletelyReducibleNilpotentMatGroup(g9);
false

gap> g10 := MaximalAbsolutelyIrreducibleNilpotentMatGroup(24,5,2);
<matrix group with 17 generators>
gap> SizeOfNilpotentMatGroup(g10);
173946175488
gap> IsCompletelyReducibleNilpotentMatGroup(g10);
true

gap> g11 := MonomialNilpotentMatGroup(96);
<matrix group with 31 generators>
gap> SizeOfNilpotentMatGroup(g11);
6442450944
gap> IsCompletelyReducibleNilpotentMatGroup(g11);
true
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Using the library of primitive nilpotent groups}

This section gives examples of applying the functions from the
\package{Nilmat} library of primitive nilpotent subgroups of $GL(n,q)$.

\beginexample
gap> L0 := NilpotentPrimitiveMatGroups(2,3,1);
[ Group([ [ [ 0*Z(3), Z(3)^0 ], [ Z(3)^0, Z(3)^0 ] ] ]),
  Group([ [ [ Z(3)^0, 0*Z(3) ], [ 0*Z(3), Z(3)^0 ] ],
      [ [ Z(3), Z(3)^0 ], [ Z(3), Z(3) ] ],
      [ [ Z(3)^0, 0*Z(3) ], [ 0*Z(3), Z(3) ] ] ]),
  Group([ [ [ Z(3)^0, 0*Z(3) ], [ 0*Z(3), Z(3)^0 ] ],
      [ [ 0*Z(3), Z(3)^0 ], [ Z(3), 0*Z(3) ] ],
      [ [ Z(3), Z(3) ], [ Z(3), Z(3)^0 ] ] ]) ]
gap> SizesOfNilpotentPrimitiveMatGroups(2,3,1);
[ 8, 8, 16 ]
gap> List(L0,Size);
[ 8, 8, 16 ]

gap> L1 := NilpotentPrimitiveMatGroups(2,2,10);;
gap> Length(L1);
40
gap> Size(L1[38]);
209715
gap> s := SizesOfNilpotentPrimitiveMatGroups(2,2,10);;
[ 5, 15, 25, 41, 55, 75, 123, 155,
165, 205, 275, 451, 465, 615, 775, 825, 1025, 1271, 1353, 1705,
2255, 2325, 3075, 3813, 5115, 6355, 6765, 8525, 11275, 13981,
19065, 25575, 31775, 33825, 41943, 69905, 95325, 209715,
349525, 1048575 ]

gap> L2 := NilpotentPrimitiveMatGroups(55,3,1);;
gap> Length(L2);
114

gap> L3 := NilpotentPrimitiveMatGroups(6,3,3);;
gap> Length(L3);
110

gap> L4 := NilpotentPrimitiveMatGroups(22,11,1);;
gap> Length(L3);
1002
\endexample

The lists `L1' and `L2' contain only abelian groups, while `L3' and
`L4' contain non-abelian nilpotent groups.