%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{ANU Sq Package}
\index{Sq}

'Sq( <G>, <L> )'

The function  'Sq' is  the  interface to the  Soluble Quotient standalone
program.

Let <G> be  a finitely presented group  and let <L> be  a list  of lists.
Each of these lists is a list of integer pairs [$p_i$,$c_i$], where $p_i$
is  a prime and  $c_i$ is a  non-negative integer and $p_i \not= p_{i+1}$
and $c_i$ positive for  $i < k.$   'Sq' computes a  consistent
power conjugate   presentation  for a  finite  soluble group  given  as a
quotient of the finitely presented group <G> which is described by <L> as
follows.

Let  $H$ be a  group and  $p$ a  prime.  The  series  $$H = {P}^p_0(H)\ge
{P}^p_1(H)\ge\cdots\,\,\hbox  to  1.5   cm{\hfil  with\ }    {P}^p_i(H) =
[{P}^p_{i-1}(H),H] \left({P}^p_{i-1} (H)\right)^p$$ for $i  \ge 1$ is the
{\it lower exponent-$p$ central series} of $H.$

For $1 \le i \le k$ and $0 \le j \le  c_i$ define the list ${\rm L}_{i,j}
=   [(p_1,c_1),\ldots,  (p_{i-1},c_{i-1}),(p_{i}, j)    ].$ Define  ${\rm
L}_{1,0}(G) = G.$ For $1  \le i \le  k$ and $1  \le j \le c_i$ define the
subgroups  $${\rm L}_{i,j}(G) =  {\rm  P}_{j}^{p_i}( {\rm L}_{i,0}(G) )$$
and for $1  \le i <  k$ define the  subgroups $${\rm L}_{i+1,0}(G) = {\rm
L}_{i,c_i}(G)$$ and ${\rm L}(G)  = {\rm  L}_{k,c_k}(G).$ Note that  ${\rm
L}_{i,j}(G) \ge {\rm L}_{i,j+1}(G)$ holds for $j < c_i.$

The chain of subgroups $$G  = {\rm L}_{1,0}(G)  \ge {\rm L}_{1,1}(G)  \ge
\cdots  \ge {\rm L}_{1,c_1}(G)    = {\rm L}_{2,0}(G)\ge \cdots   \ge {\rm
L}_{k,c_k}(G) = {\rm  L}(G)  $$   is   called  the  {\it  soluble   ${\rm
L}$-series} of $G.$

'Sq' computes  a  consistent  power  conjugate  presentation for  $G/{\rm
L}(G),$ where  the   presentation exhibits a  composition  series  of the
quotient group which is a refinement of the soluble ${\rm L}$-series.  An
epimorphism from $G$ onto $G/{\rm L}(G)$ is listed in comments.

The algorithm proceeds by computing power conjugate presentations for the
quotients  $G/{\rm L}_{i,j}(G)$ in   turn.   Without loss of   generality
assume that a  power conjugate presentation  for $G/{\rm L}_{i,j}(G)$ has
been computed  for $j < c_i.$ The  basic step computes a  power conjugate
presentation for $G/{\rm L}_{i,j+1}(G).$ The group ${\rm L}_{i,j}(G)/{\rm
L}_{i,j+1}(G)$  is  a  $p_{i}$-group.   If  during  the  basic step it is
discovered that ${\rm  L}_{i,j}(G)   = {\rm L}_{i,j+1}(G),$  then   ${\rm
L}_{i+1,0}(G)$ is set to ${\rm L}_{i,j}(G).$

Note that during the basic step the vector enumerator is called.

|    f := FreeGroup( "a", "b" );
     f := f/[ (f.1*f.2)^2*f.2^-6, f.1^4*f.2^-1*f.1*f.2^-9*f.1^-1*f.2 ];
     gap> g := Sq( f, [[2,1],[3,1],[2,2],[3,2]] );
     rec(
      generators := [ a.1, a.2, a.3, a.4, a.5, a.6, a.7, a.8 ],
      relators := [ a.1^2*a.3^-1, a.1^-1*a.2*a.1*a.4^-1*a.2^-2, 
          a.2^3*a.5^-1, a.1^-1*a.3*a.1*a.3^-1, 
          a.2^-1*a.3*a.2*a.6^-1*a.5^-1*a.4^-1*a.3^-1, 
          a.3^2*a.7^-1*a.5^-1, a.1^-1*a.4*a.1*a.7^-1*a.4^-1*a.3^-1, 
          a.2^-1*a.4*a.2*a.8^-1*a.7^-1*a.6^-2*a.3^-1, 
          a.3^-1*a.4*a.3*a.8^-2*a.7^-2*a.5^-1*a.4^-1, 
          a.4^2*a.8^-2*a.7^-2*a.6^-2*a.5^-1, 
          a.1^-1*a.5*a.1*a.8^-1*a.7^-1*a.6^-1*a.5^-1, a.2^-1*a.5*a.2*a.5^-1, 
          a.3^-1*a.5*a.3*a.8^-2*a.6^-1*a.5^-1, a.4^-1*a.5*a.4*a.7^-1*a.5^-1, 
          a.5^2, a.1^-1*a.6*a.1*a.8^-1*a.7^-2*a.6^-1, 
          a.2^-1*a.6*a.2*a.8^-2*a.6^-2, a.3^-1*a.6*a.3*a.8^-2*a.7^-2*a.6^-2, 
          a.4^-1*a.6*a.4*a.8^-1*a.7^-2, a.5^-1*a.6*a.5*a.8^-2*a.6^-2, a.6^3, 
          a.1^-1*a.7*a.1*a.6^-2, a.2^-1*a.7*a.2*a.7^-2*a.6^-2, 
          a.3^-1*a.7*a.3*a.8^-1*a.7^-1*a.6^-2, a.4^-1*a.7*a.4*a.6^-1, 
          a.5^-1*a.7*a.5*a.7^-2, a.6^-1*a.7*a.6*a.8^-1*a.7^-1, a.7^3, 
          a.1^-1*a.8*a.1*a.8^-2, a.2^-1*a.8*a.2*a.8^-1,
          a.3^-1*a.8*a.3*a.8^-1, a.4^-1*a.8*a.4*a.8^-1,
          a.5^-1*a.8*a.5*a.8^-1, a.6^-1*a.8*a.6*a.8^-1, 
          a.7^-1*a.8*a.7*a.8^-1, a.8^3 ] ) |

This implementation was developed in C by

Alice C. Niemeyer
Department of Mathematics
University of Western Australia
Nedlands, WA 6009
Australia

email: alice@maths.uwa.edu.au 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the ANU Sq Package}

The ANU Sq  is written in C  and the package  can only be installed under
UNIX.  It has been tested on DECstation running Ultrix, a HP 9000/700 and
HP 9000/800 running HP-UX, a MIPS running  RISC/os Berkeley, a PC running
NnetBSD 0.9, and SUNs running SunOS.

It requires Steve Linton\'s vector enumerator (either as standalone or as
GAP share  library). Make sure  that   it is installed before   trying to
install the ANU Sq.

If you have a complete binary and  source distribution  for your machine,
nothing has  to  be done if  you want  to use the   ANU Sq  for  a single
architecture. If you want to use  the ANU Sq  for machines with different
architectures skip  the extraction and compilation  part  of this section
and proceed with the creation of shell scripts described below.

If you have a complete source distribution,  skip the  extraction part of
this section and proceed with the compilation part below.

In the example we will assume that you, as user 'gap', are installing the
ANU Sq package for use by several users  on a network of two DECstations,
called   'bert' and  'tiffy',   and a  Sun   running  SunOS  5.3,  called
'galois'. We  assume  that {\GAP}  is also   installed on these  machines
following the instructions given in "Installation of GAP for UNIX".

Note that certain parts  of  the  output  in the examples should  only be
taken as rough outline, especially file sizes and file dates are *not* to
be taken literally.

First of  all you have to  get the file  'anusq.zoo' (see "Getting GAP").
Then you  must locate the {\GAP} directory  containing 'lib/' and 'doc/',
this is usually  'gap3r4p0' where '0'  is to be  replaced by  the current
patch level.

|    gap@tiffy:~ > ls -l
    drwxr-xr-x  11 gap     1024 Nov  8  1991 gap3r4p0
    -rw-r--r--   1 gap   360891 Dec 27 15:16 anusq.zoo
    gap@tiffy:~ > ls -l gap3r4p0
    drwxr-xr-x   2 gap     3072 Nov 26 11:53 doc
    drwxr-xr-x   2 gap     1024 Nov  8  1991 grp
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 lib
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 pkg
    drwxr-xr-x   2 gap     2048 Nov 26 09:42 src
    drwxr-xr-x   2 gap     1024 Nov 26 09:42 tst|

Unpack the package using 'unzoo'  (see "Installation  of GAP for  UNIX").
Note that  you must be in the  directory containing 'gap3r4p0'  to unpack
the files.    After you have  unpacked   the source  you may  remove  the
*archive-file*.

|    gap@tiffy:~ > unzoo x anusq
    gap@tiffy:~ > cd gap3r4p0/pkg/anusq
    gap@tiffy:../anusq> ls -l
    -rw-r--r--   1 gap     5232 Apr 10 12:40 Makefile
    -rw-r--r--   1 gap    13626 Mar 28 16:31 README
    drwxr-xr-x   2 gap      512 Apr 10 13:30 bin
    drwxr-xr-x   2 gap      512 Apr  9 20:28 examples
    drwxr-xr-x   2 gap      512 Apr 10 14:22 gap
    -rw-r--r--   1 gap     5272 Apr 10 13:34 init.g
    drwxr-xr-x   2 gap     1024 Apr 10 13:41 src
    -rwxr-xr-x   1 gap      525 Mar 28 15:50 testSq |

Typing 'make' will produce a list of possible target.

|gap@tiffy:../anusq > make
usage: 'make <target> EXT=<ext>'  where <target> is one of
'bsd-gcc'    for Berkeley UNIX with GNU cc 2
'bsd-cc'     for Berkeley UNIX with cc
'usg-gcc'    for System V UNIX with cc
'usg-cc'     for System V UNIX with cc
'clean'      remove all created files

   where <ext> should be a sensible extension, i.e.,
   'EXT=-sun-sparc-sunos' for SUN 4 or 'EXT=' if the SQ only
   runs on a single architecture

   additional C compiler and linker flags can be passed with
   'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>',
   i.e., 'make bsd-cc COPTS="-DTAILS -DCOLLECT"', see the
   README file for details on TAILS and COLLECT.

   set ME if the vector enumerator is not started with the 
   command '`pwd`/../ve/bin/me',
   i.e., 'make bsd-cc ME=/home/ve/bin/me'.|

Select  the target you  need.  The DECstations  are running Ultrix, so we
chose 'bsd-gcc'.

|    gap@tiffy:../anusq > make bsd-gcc EXT=-dec-mips-ultrix
    # you will see a lot of messages |

Now repeat the compilation for the Sun run SunOS  5.3. *Do not* forget to
clean up.

|    gap@tiffy:../anusq > rlogin galois
    gap@galois:~ > cd gap3r4p0/pkg/anusq
    gap@galois:../anusq > make clean
    gap@galois:../src > make usg-cc EXT=-sun-sparc-sunos
    # you will see a lot of messages and a few warnings
    gap@galois:../anusq > exit
    gap@tiffy:../anusq > |

Switch into the subdirectory 'bin/'  and create a  script which will call
the correct binary for each machine. A skeleton  shell script is provided
in 'bin/Sq.sh'.

|    gap@tiffy:../anusq > cd bin
    gap@tiffy:../bin > cat > sq
    |\#|!/bin/csh
    switch ( `hostname` )
      case 'tiffy':
        exec $0-dec-mips-ultrix $* ;
        breaksw ;
      case 'bert':
        setenv ANUSQ_ME_EXEC /rem/tiffy/usr/local/bin/me ;
        exec $0-dec-mips-ultrix $* ;
        breaksw ;
      case 'galois':
        exec $0-sun-sparc-sunos $* ;
        breaksw ;
      default:
        echo "sq: sorry, no executable exists for this machine" ;
        breaksw ;
    endsw
    |<ctr>-'D'|
    gap@tiffy:../bin > chmod 755 Sq
    gap@tiffy:../bin > cd .. |

Now it is time to test  the installation.  The  first test will only test
the ANU Sq.

|    gap@tiffy:../anusq > ./testSq
    Testing examples/grp1.fp  . . . . . . . . succeeded
    Testing examples/grp2.fp  . . . . . . . . succeeded
    Testing examples/grp3.fp  . . . . . . . . succeeded |

If there is a problem  and you get an error message saying 'me not found',
set the  environment variable 'ANUSQ\_ME\_EXEC'  to the module enumerator
executable and try again.

The  second test will  test the link between {\GAP}   and the ANU Sq.  If
everything goes well you should not see any message.

|    gap@tiffy:../anusq > gap -b
    gap> RequirePackage( "anusq" );
    gap> ReadTest( "gap/test1.tst" );
    gap> |

You may now repeat the tests for the other machines.
