%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  Cubefree.tex        Cubefree documentation             Heiko Dietrich
%%
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Functionality of the Cubefree package}

\atindex{Functionality of the Cubefree package}{@functionality %
                                            of the {\Cubefree} package}

This chapter describes the methods available from the {\Cubefree} package.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{New methods}

This section lists the implemented functions.


\>ConstructAllCFGroups( <order> ) F

The input <order> has to be a positive cubefree integer. The output is a complete and irredundant list of isomorphism
type representatives of groups of this size. If possible, the groups are given
as pc groups and as permutations groups otherwise.

\>ConstructAllCFSolvableGroups( <order> ) F

The input <order> has to be a positive cubefree integer. The output is a complete and irredundant list of isomorphism
type representatives of solvable groups of this size. The groups are given as pc groups.

\>ConstructAllCFNilpotentGroups( <order> ) F

The input <order> has to be a positive cubefree integer. The output is a complete and irredundant list of isomorphism
type representatives of nilpotent groups of this size. The groups are given as pc groups.

\>ConstructAllCFSimpleGroups( <order> ) F

The input <order> has to be a positive cubefree integer. The output is a complete and irredundant list of isomorphism
type representatives of simple groups of this size. In particular, there
exists either none or exactly one simple group of the given order.

\>ConstructAllCFFrattiniFreeGroups( <order> ) F

The input <order> has to be a positive cubefree integer. The output is a complete and irredundant list of isomorphism
type representatives of Frattini-free groups of this size.

\>NumberCFGroups( <n>[, <bool> ] ) F

The input <n> has to be a positive cubefree integer and the output is the number of all
cubefree groups of order <n>. The {\SmallGroups} library  is used for squarefree
orders, orders of the type $p^2$ and $p^2q$, and cubefree orders less than
50000. Only if <bool> is set to false, then only  the squarefree
orders and orders of the type $p^2$ and $p^2q$,are taken from the {\SmallGroups}  library.


\>NumberCFSolvableGroups( <n>[, <bool> ] ) F 

The input <n> has to be a positive cubefree integer and the output is the number of all
cubefree solvable groups of order <n>. The {\SmallGroups} library  is used for squarefree
orders, orders of the type $p^2$ and $p^2q$, and cubefree orders less than
50000. Only if <bool> is set to false, then only  the squarefree
orders and orders of the type $p^2$ and $p^2q$,are taken from the {\SmallGroups} library.


\>CountAllCFGroupsUpTo( <n>[, <bool> ]) F  

The input is a positive integer <n> and the output is a list $L$ of size <n> such that
$L[i]$ contains the number of isomorphism types of groups of order $i$ if $i$
is cubefree and $L[i]$ is not bound, otherwise, $1\leq i \leq n$. The
{\SmallGroups} library  is used for squarefree orders, orders of the type $p^2$ and $p^2q$, and cubefree orders less than
50000. Only if <bool> is set to false, then only  the squarefree
orders and orders of the type $p^2$ and $p^2q$ are taken from the
{\SmallGroups} library. This function was implemented only for experimental
purposes and its implementation could be improved.


\>CubefreeOrderInfo( <n>[, <bool> ] ) F

This function displays some (very vague)
information about the complexity of the construction of the groups of
(cubefree) order <n>. It returns the number of possible pairs <(a,b)> where
<a> is the order of a Frattini-free group <F> with socle <S> of order <b> which
has to be constructed in order to construct all groups of order <n>: In fact,
for each of these pairs <(a,b)> one would have to construct up to conjugacy all
subgroups of order <a/b> of Aut<(S)>. The sum of the numbers of these
subgroups for all pairs  <(a,b)> as above is the number of groups of order
<n>. Thus the output of `CubefreeOrderInfo' is a trivial lower bound for the number of
groups of order <n>. There is no additional information
displayed if <bool> is set to false.

\>CubefreeTestOrder( <n> ) F

The input has to be a cubefree integer between 1 and 50000. This function
tests the functionality of {\Cubefree}, i.e. functions (1)--(7), and compares it with the data
of the {\SmallGroups} library. It returns true if everything is okay,
otherwise an error message will be displayed.

\>IsCubeFreeInt( <n> ) P

The output is <true> if <n> is a cubefree integer and <false> otherwise.


\>IsSquareFreeInt( <n> ) P

The output is <true> if <n> is a squarefree integer and <false> otherwise.

\>IrreducibleSubgroupsOfGL( <n>, <q> ) O

The current version of this function allows only <n>=2. The input <q> has to be a prime-power <q>$=p^r$ with $p\geq 5$ a prime. The output
is a list of all irreducible subgroups of GL$(2,q)$ up to conjugacy.

\>RewriteAbsolutelyIrreducibleMatrixGroup( <G> ) F

The input $G$ has to be an absolutely irreducible matrix group over a finite
field GF$(q)$. If possible, the output is
$G$ rewritten over the subfield of GF$(q)$ generated by the traces of the
elements of $G$. If no rewriting is possible, then the
input $G$ is returned. 


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Comments on the implementation}

This section provides some information about the implementations.


*ConstructAllCFGroups*

The function `ConstructAllCFGroups' constructs all groups of a given
cubefree order up to isomorphism using the Frattini Extension Method as described in \cite{Di05},
  \cite{DiEi05}, \cite{BeEia}, and \cite{BeEib}. One step in the Frattini
  Extension Method is to compute Frattini extensions 
  and for this purpose some already implemented
methods of the required \GAP ~package \GrpConst ~are used. 

Since `ConstructAllCFGroups' requires only
some special types of irreducible subgroups of GL$(2,p)$ (e.g. of cubefree order), it
contains a modified internal version of
`IrreducibleSubgroupsOfGL'. This means that the latter is not called explicitely by
`ConstructAllCFGroups'.

~

~

*ConstructAllCFSimpleGroups and ConstructAllCFNilpotentGroups*

The construction of simple or nilpotent groups of cubefree
order is rather easy, see \cite{Di05} or \cite{DiEi05}. In particular, the
methods used in these cases are independent from the methods used in the general cubefree case.


*CountAllCFGroupsUpTo*

As described in \cite{Di05} and \cite{DiEi05}, every cubefree group $G$ has
the form $G=A\times I$ where $A$ is trivial or non-abelian simple and $I$ is
solvable. Further, there is a one-to-one correspondence between the solvable
cubefree groups and <some> solvable Frattini-free groups. This one-to-one
correspondence allows to count the number of groups of a given cubefree order without
computing any Frattini extension.
To reduce runtime, the
computed irreducible and reducible subgroups of the general linear groups
GL$(2,p)$ and also the number of the computed solvable
Frattini-free groups are stored during the whole computation. This is very
memory consuming but reduces the runtime significantly. The alternative is to
run a loop over `NumberCFGroups'.
This function was implemented only for experimental purposes and its
implementation could be improved.

*IrreducibleSubgroupsOfGL*

If the input is a matrix group over GF$(q)$, then the algorithm needs to
construct GF$(q^3)$ or GF$(q^6)$ internally. 



*RewriteAbsolutelyIrreducibleMatrixGroup*

The function `RewriteAbsolutelyIrreducibleMatrixGroup' as described
algorithmically in
\cite{GlHo97} is a probabilistic Las Vegas algorithm; it retries until a correct
answer is returned. If the input is $G\leq$GL$(d,p^r)$, then the
expected runtime is $O(rd^3)$.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Comments on the efficiency}

The package {\GrpConst} contains several implementations of algorithms to
construct groups of a given order. One of these algorithms is the Frattini
extension method, see Chapter 1. The algorithm used in
{\Cubefree} is a modification of the Frattini extension method to the case of
cubefree orders. 

The advantage of this modification is that the isomorphism
problem at the construction of Frattini extensions is solved completely on a
theoretic level. Also, the construction of the Frattini-free groups up to
isomorphism is reduced to the determination of certain subgroups of groups of
the type GL$(2,p)$ and $C_{p-1}$, $p$ a prime, and to the construction of subdirect products
of these subgroups. As this is exponential, this is a main bottleneck of the current implementation.

A modification of the Frattini extension method to squarefree orders yields a
powerful 
construction algorithm for squarefree groups which is based on number theory
only. An implementation of this algorithm can be found
in the {\SmallGroups} library. Thus for squarefree
groups one should definitely use `AllSmallGroups' and `NumberSmallGroups'
instead of the functions of {\Cubefree}. The same holds for groups of order
$p^2$ or $p^2q$.

Moreover, using the functionality of {\Cubefree}, the {\SmallGroups} library now
contains all groups of cubefree order at most 50000. Hence, also in this case,
one should prefer `AllSmallGroups' and `NumberSmallGroups' to access the data
of the library directly.

For all other cubefree  orders <n> one can try to use
{\Cubefree} to construct or count the corresponding groups. Note, that the
success of these computations depends basically on the complexity and number
theory of the
prime-power factorization of <n>. For each prime $p$ with $p^2\mid n$ one
might have to construct subgroups of GL$(2,p)$ and subdirect products
involving these subgroups. One can use the info class `InfoCF' to get some
information during the computation. 
In order to construct subdirect products, we need a permutation representation of these
matrix groups. To rewrite them at once, we compute a
permutation representation of GL$(2,p)$ and apply this isomorphism to the
constructed subgroups. Unfortunately, this is quite time and memory consuming
for bigger primes.

In other words,  {\Cubefree} can note handle <unreasonable>
cubefree orders. To get a rough idea of the complexity of the computation of
groups of order $n$ and to get a trivial  lower bound for the number of
groups, one can use `CubefreeOrderInfo(n)'.

At the end of this section we consider the quotient $q(n)$ of `NumberSmallGroups(n)'
and  `CubefreeOrderInfo(n)' for cubefree $1\leq n\leq
50000$. Although for most of these integers we have a small quotient, note
that $q(n)$ seems to be unbounded in general. There are 41597 cubefree integers between $1$ and $50000$ and $26414$
of these integers fulfill $q(n)=1$. Moreover, 13065 of these integers fulfill
$1\< q(n)\< 5$ and the remaining 2118 integers have $5\leq q(n)\leq
54$; e.g. $n=2^2.3.5.7^2.13$ has $q(n)=1221/23$. 










%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{An example session}

In this section we outline some examples of applications of
the methods described above. We
included runtimes for all examples, but omitted the output
in some cases, since it would be too long to be printed.
The runtimes have been obtained on an Intel(R) Pentium(R) 4 CPU 3.00GHz PC running under Linux.

\beginexample
gap> n:=5^2*7*13^2*67^2*97*107;
1377938614325
gap> CubefreeOrderInfo(n,false);
12
gap> Length(ConstructAllCFGroups(n));time;
12
53111
\endexample
\beginexample
gap> n:=19^2*23^2*29*37*73^2*107^2;
12501895704027377
gap> CubefreeOrderInfo(n,false);
24
gap> NumberCFGroups(n);time;
24
190536
gap> Length(ConstructAllCFGroups(n));time;
24
948319
\endexample
\beginexample
gap> n:=5^2*13*23^2*43^2*191;
60716861075
gap> CubefreeOrderInfo(n,false);
16
gap> Length(ConstructAllCFGroups(n)); time;
16
29146
\endexample

Now we compute some more data.

\beginexample
gap>  n:=2*2*3*11*17*67;
150348
gap> CubefreeOrderInfo(n,false);
20
gap> NumberCFGroups(n);time;
145
12073
gap> Length(ConstructAllCFGroups(n)); time;
145
20757
gap> NumberCFSolvableGroups(n);time;
144
11925
gap> Length(ConstructAllCFSolvableGroups(n)); time;
144
18893
gap> Length(ConstructAllCFFrattiniFreeGroups(n)); time;
109
14421
gap> Length(ConstructAllCFNilpotentGroups(n));time;
2
12
gap> Length(ConstructAllCFSimpleGroups(n));time;
1
8
\endexample


We consider another example with some info class output.

\beginexample
gap> SetInfoLevel(InfoCF,1);
gap> ConstructAllCFGroups(4620);;time;
#I  Construct all groups of order 4620.
#I    Compute solvable Frattini-free groups of order 2310.
#I    Compute solvable Frattini-free groups of order 4620.
#I  Construct 138 Frattini extensions.
#I    Compute solvable Frattini-free groups of order 77.
#I  Construct 1 Frattini extensions.
#I    Compute solvable Frattini-free groups of order 7.
#I  Construct 1 Frattini extensions.
15501
\endexample


\beginexample
gap> n:=101^2*97*37^2*29^2;
1139236591513
gap> CubefreeOrderInfo(n,false);
8
gap> NumberCFGroups(n);time;
8
36
gap> SetInfoLevel(InfoCF,1);
gap> ConstructAllCFGroups(n);time;
#I  Construct all groups of order 1139236591513.
#I    Compute solvable Frattini-free groups of order 10512181.
#I    Compute solvable Frattini-free groups of order 304853249.
#I    Compute solvable Frattini-free groups of order 388950697.
#I    Compute solvable Frattini-free groups of order 1061730281.
#I    Compute solvable Frattini-free groups of order 11279570213.
#I    Compute solvable Frattini-free groups of order 30790178149.
#I    Compute solvable Frattini-free groups of order 39284020397.
#I    Compute solvable Frattini-free groups of order 1139236591513.
#I  Construct 8 Frattini extensions.
[ <pc group of size 1139236591513 with 7 generators>,
  <pc group of size 1139236591513 with 7 generators>,
  <pc group of size 1139236591513 with 7 generators>,
  <pc group of size 1139236591513 with 7 generators>,
  <pc group of size 1139236591513 with 7 generators>,
  <pc group of size 1139236591513 with 7 generators>,
  <pc group of size 1139236591513 with 7 generators>,
  <pc group of size 1139236591513 with 7 generators> ]
1848
\endexample



The last example considers the cubefree order less than 50000 for which the
number of groups with this order is maximal: there are 3093 groups of order 44100.

\beginexample
gap> n:=2*2*3*3*5*5*7*7;
44100
gap> CubefreeOrderInfo(n,false);
100
gap> NumberCFSolvableGroups(n,false);time;
3087
572639
gap> Length(ConstructAllCFSolvableGroups(n)); time;
3087
843085
gap> NumberCFGroups(n,false);time;
3093
719245
gap> Length(ConstructAllCFGroups(n)); time;
3093
1016763
gap> Length(ConstructAllCFFrattiniFreeGroups(n)); time;
1305
504451
gap> Length(ConstructAllCFNilpotentGroups(n));time;
16
180
\endexample


%%
%% strange behaviour: (cont. of example 44100):
%%
%\beginexample
%gap> NumberCFGroups(n,false);time;
%3093
%596005
%gap> NumberCFSolvableGroups(n,false);time;
%3087
%748827
%\endexample
%
%As `NumberCFSolvableGroups' is called internally from `NumberCFGroups',
%it is expected that its runtime is less than the runtime
%of `NumberCFGroups'. If we change the order of the calls, then we get
%
%\beginexample
%gap> NumberCFSolvableGroups(n,false);time;
%3087
%623887
%gap> NumberCFGroups(n,false);time;
%3093
%723949
%\endexample



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Accuracy check}

We have compared the results of `ConstructAllCFGroups' with the library of
cubefree groups of {\SmallGroups}. Further, we compared the 
solvable groups constructed by `IrreducibleSubgroupsOfGL' with the library of
{\IrredSol}. We have also done random isomorphism tests to verify that the
list of groups we computed is not redundant. 

One can call the following test files. The first one constructs some groups of order at most 2000 and compares the results with the
{\SmallGroups} library:


`RereadPackage(\"cubefree\",\"tst/testQuick.g\");'


The command

`RereadPackage(\"cubefree\",\"tst/testBig.g\");'

constructs the solvable groups of a random cubefree (but not squarefree) order at most $2^{28}-1$ and does a random isomorphism test. Depending on the chosen number, the computation might not terminate due to memory problems.



The following constructs the groups of three random cubefree orders less than 50000 compares the result with the
{\SmallGroups} library. Depending on the chosen orders, this may take a while:

`RereadPackage(\"cubefree\",\"tst/testSG.g\");'


The test file <testSGlong.g> constructs all cubefree groups of order at most
50000 compares the results with the
{\SmallGroups} library. There will be a positive progress report every 50th
order so that you can abort the test whenever you want.

`RereadPackage(\"cubefree\",\"tst/testSGlong.g\");'

Three of these four test files use the function `CubefreeTestOrder', see Section 2.1. 

The last test file compares some results of `IrreducibleSubgroupsOfGL' with the
database of {\IrredSol}. This may take a while:

`RereadPackage(\"cubefree\",\"tst/testMat.g\");'




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

