%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  install.tex     ANUPQ documentation - installation      Werner Nickel
%%
%%
%H  $Id: install.tex,v 1.17 2006/01/24 04:57:16 gap Exp $
%%
%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Chapter{Installing the ANUPQ Package}

The ANU  `pq' program is  written in C  and the package can  be installed
under UNIX  and in environments  similar to 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  NeXTstation running NeXTSTEP 3.0, a SUN
running  SunOS and an  Intel Pentium  based PC  running Linux  or Windows
equipped with cygwin.

The current version of the  {\ANUPQ}  package  requires  {\GAP}~4.4,  and
version 1.2 of the {\AutPGrp} package. If you still have  {\GAP}~4.3  (at
least fix4), then you must  use  {\ANUPQ}~2.2,  and  {\AutPGrp}~1.1.  You
should not use earlier versions of the {\ANUPQ} package  since  they  are
known to have bugs.

To install the {\ANUPQ} package, move the file `anupq-<XXX>.zoo' for some
version number <XXX> into the  `pkg'  directory  in  which  you  plan  to
install {\ANUPQ}. Usually, this  will  be  the  directory  `pkg'  in  the
hierarchy of your version of {\GAP}~4; it is  however  also  possible  to
keep an additional `pkg' directory in your private directories. The  only
essential difference  with  installing  {\ANUPQ}  in  a  `pkg'  directory
different to the {\GAP}~4 home directory is that one  must  start  {\GAP}
with the `-l' switch (see Section~"ref:Command  Line  Options"),  e.g.~if
your private `pkg' directory is a subdirectory of `mygap'  in  your  home
directory you might type:

%begintt
\){\kernttindent}gap -l ";<myhomedir>/mygap"
%endtt

where <myhomedir> is the  path  to  your  home  directory,  which  (since
{\GAP}~4.3) may be replaced  by  a  tilde.  The  empty  path  before  the
semicolon is  filled  in  by  the  default  path  of  the  {\GAP}~4  home
directory.

Then, in your chosen `pkg' directory, unzoo `anupq-<XXX>.zoo' by

%\begintt
\){\kernttindent}unzoo -x anupq-<XXX>
%\endtt

Change to the newly created `anupq'  directory.  Now  you  need  to  call
`configure <path>' where <path> is the path to the {\GAP} home directory.
So for example if you install the package in  the  main  `pkg'  directory
call

\begintt
./configure ../..
\endtt

What this does is look for a file `sysinfo.gap' in the root directory  of
{\GAP} in order to determine an architecture name for the subdirectory of
`bin' in which to put the compiled `pq' binary. This only makes sense  if
{\GAP} was compiled for the same architecture that `pq' will be.  If  you
have a shared file system mounted across  different  architectures,  then
you should run `configure' and `make' for {\ANUPQ} for each  architecture
immediately after compiling {\GAP} on the same architecture.

If you had to install the package in your own directory but wish  to  use
the system {\GAP}~4 then you will need to find out what <path> is. To  do
this, start up {\GAP} and find  out  what  {\GAP}'s  root  path  is  from
finding the value of the  variable  `GAPInfo.RootPaths'  (in  {\GAP}~4.4;
this was `GAP_ROOT_PATHS' prior to {\GAP}~4.4), e.g.

\begintt
gap> GAPInfo.RootPaths;
[ "/usr/local/lib/gap4r4/" ]
\endtt

would tell you to use `/usr/local/lib/gap4r4' for <path>.

The `configure' command will fetch the architecture type for which {\GAP}
has been compiled  last,  create  a  `Makefile'  and  list  a  number  of
``targets'' to call `make' with. If you have one of  the  standard  Linux
(or NetBSD or FreeBSD) systems with `gcc', wish  to  compile  with  `-O2'
optimisation, and have `gmp'  with  its  include  and  library  files  in
`/usr/local/include' and  `/usr/local/lib',  respectively,  you  can  now
simply call

\begintt
make
\endtt

to compile the binary and to install it in the appropriate place.

If you need a special target, e.g.~you don't have `gmp' or are not  on  a
Linux  system,  and  the  targets  displayed  on  the  screen  after  the
`configure' step rushed past your eyes and you can't scroll back  to  see
them, you can ``pipe'' those same targets through `less' or `more',  e.g.
with `more':

\begintt
make unknown || more
\endtt

An abbreviation of the target list is as follows:

\begintt
'linux-iX86-gcc2-gmp'      for IBM x86 PCs under linux/BSD with GNU cc 2 and mp
'linux-iX86-cc-gmp'        for IBM x86 PCs under linux/BSD with cc and GNU mp
'linux-iX86-gcc2'          for IBM x86 PCs under linux/BSD with GNU cc 2
'linux-iX86-cc'            for IBM x86 PCs under linux/BSD with cc (GNU)
'iX86-pc-cygwin-gcc-gmp'   for IBM x86 PCs under CYGWIN with GNU cc and GNU mp
'iX86-pc-cygwin-gcc'       for IBM x86 PCs under CYGWIN with GNU cc
[... 16 lines deleted ...]
'sunos-gcc2-gmp'           for SunOS with GNU cc 2 and gmp
'sunos-cc-gmp'             for SunOS with cc and GNU mp
'sunos-gcc2'               for SunOS with GNU cc 2
'sunos-cc'                 for SunOS with cc
'unix-gmp'                 for a generic unix system with cc and GNU mp
'unix'                     for a generic unix system with cc
'clean'                    remove all created files

   targets are listed according to preference,
   i.e., 'sunos-gcc2' is better than 'sunos-cc'
   no target is the same as choosing 'linux-iX86-gcc2-gmp'
   additional C compiler and linker flags can be passed with
   'make <target> COPTS=<compiler-opts> LOPTS=<linker-opts>',
   e.g., 'make sunos-cc COPTS=-g LOPTS=-g'.

   set GAP if GAP4 is not started with the command 'gap',
   e.g., 'make sunos-cc GAP=/usr/local/bin/gap4'.

   in order to use the GNU multiple precision (gmp) set
   'GNUINC' (default '/usr/local/include') and 
   'GNULIB' (default '/usr/local/lib')

   do 'make unknown || more' to see these targets again via more
\endtt

Let's suppose that the `linux-iX86-gcc2-gmp' target does not satisfy your
requirements, that your system is Solaris 2.8 (i.e.~SunOS 5.8), you  have
`gmp' but its `include' and `lib' directories  are  somewhere  else,  and
that `gap4' is the command used to start  {\GAP}~4.  Then  the  following
might be the appropriate `make' call:

\begintt
make sunos-gcc2-gmp GAP=gap4 GNUINC=/opt/local/include GNULIB=/opt/local/lib
\endtt

If you  don't  have  the  *GNU*  multiple  precision  arithmetic  (`gmp')
installed on your system, don't worry,  `gmp'  is  *not  required*;  just
select an appropriate target without `-gmp'.

\indextt{ANUPQ_GAP_EXEC!environment variable}
The path of {\GAP} (see *Note* below) used by the `pq' binary (the  value
`GAP' is set to in the `make' command) may be over-ridden by setting  the
environment variable `ANUPQ_GAP_EXEC'. These values are only of  interest
when the `pq' program is run  as  a  standalone;  however,  the  `testPq'
script assumes you have set one of these correctly (see  Section~"Testing
your ANUPQ installation"). When the `pq' program is started  from  {\GAP}
communication occurs via an iostream, so that the `pq'  binary  does  not
actually need to know a valid path for {\GAP} is this case.

*Note.* By ``path of {\GAP}'' we mean the path of  the  command  used  to
invoke {\GAP} (which  should  be  a  script,  e.g.  the  `gap.sh'  script
generated in the `bin' directory for the version of  {\GAP}  when  {\GAP}
was compiled). The usual strategy is to copy the  `gap.sh'  script  to  a
standard location, e.g. `/usr/local/bin/gap'. It is a mistake to copy the
{\GAP}  executable  `gap'   (in   a   directory   with   name   of   form
`bin/<compile-platform>')  to  the  standard   location,   since   direct
invocation of the executable results in  {\GAP}  starting  without  being
able to find its own library (a fatal error).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Testing your ANUPQ installation}

\indextt{ANUPQ_GAP_EXEC!environment variable}
Now it is time to test the  installation.  After  doing  `configure'  and
`make' you will have a `testPq' script. The script assumes that,  if  the
environment variable `ANUPQ_GAP_EXEC' is set, it is a  correct  path  for
{\GAP}, or otherwise that the `make' call that compiled the  `pq' program
set `GAP' to a correct path  for  {\GAP}  (see  Section~"Running  the  pq
program as a standalone" for more details). To run the tests, just type:

\begintt
testPq
\endtt

Some of the tests the script runs take a while. Please  be  patient.  The
script checks that you not only have a correct {\GAP} (at  least  version
4.4) installation that includes the  {\AutPGrp}  package,  but  that  the
{\ANUPQ} package and its `pq' binary interact correctly. You  should  see
something like the following output:

\begintt
Made dir: /tmp/testPq
Testing installation of ANUPQ Package (version 3.0)
 
The first two tests check that the pq C program compiled ok.
Testing the pq binary ... OK.
Testing the pq binary's stack size ... OK.
The pq C program compiled ok! We test it's the right one below.
 
The next tests check that you have the right version of GAP
for version 3.0 of the ANUPQ package and that GAP is finding
the right versions of the ANUPQ and AutPGrp packages.
 
Checking GAP ...
 pq binary made with GAP set to: /usr/local/bin/gap
 Starting GAP to determine version and package availability ...
  GAP version (4.4.6) ... OK.
  GAP found ANUPQ package (version 3.0) ... good.
  GAP found pq binary (version 1.8) ... good.
  GAP found AutPGrp package (version 1.2) ... good.
 GAP is OK.
 
Checking the link between the pq binary and GAP ... OK.
Testing the standard presentation part of the pq binary ... OK.
Doing p-group generation (final GAP/ANUPQ) test ... OK.
Tests complete.
Removed dir: /tmp/testPq
Enjoy using your functional ANUPQ package!
\endtt

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Running the pq program as a standalone}

\indextt{ANUPQ_GAP_EXEC!environment variable}
When the `pq' program is run as a standalone it sometimes  needs  to call
{\GAP} to compute stabilisers of subgroups; in doing so, it first  checks
the value of the environment variable `ANUPQ_GAP_EXEC', and uses that, if
set, or otherwise the value of `GAP' it was compiled with,  as  the  path
for  {\GAP}.  If  you  ran  `testPq'  (see  Section~"Testing  your  ANUPQ
installation") and you got both {\GAP} is `OK' and the link  between  the
`pq' binary and {\GAP} is `OK', you should be fine.  Otherwise  heed  the
recommendations of the error messages you get and run the `testPq'  until
all tests are passed.

It is especially important that the {\GAP}, whose path you  gave,  should
know where to find the {\ANUPQ} and {\AutPGrp} packages. To  ensure  this
the path should be to a shell script that invokes {\GAP}. If  you  needed
to install the needed packages in your own directory (because,  say,  you
are not a system administrator) then you should  create  your  own  shell
script that runs {\GAP} with a correct setting of the `-l' option and set
the path used by the `pq' binary to the path of that  script.  To  create
the script that runs {\GAP} it is easiest to copy the system one and edit
it, e.g. start by executing the following UNIX commands (skip the  second
step if you already have a `bin'  directory;  `you@unix>'  is  your  UNIX
prompt):

\begintt
you@unix> cd
you@unix> mkdir bin
you@unix> cd bin
you@unix> which gap
/usr/local/bin/gap
you@unix> cp /usr/local/bin/gap mygap
you@unix> chmod +x mygap
\endtt

At the second-last step use the path of {\GAP} returned by  `which  gap'.
Now hopefully you will have a copy of the script  that  runs  the  system
{\GAP} in `mygap'. Now use your favourite editor to edit the `-l' part of
the last line of `mygap' which should initially look something like:

\begintt
exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l $GAP_DIR $*
\endtt

so that it becomes (the tilde  is  a  UNIX  abbreviation  for  your  home
directory):

\begintt
exec $GAP_DIR/bin/$GAP_PRG -m $GAP_MEM -o 970m -l "$GAP_DIR;~/gapstuff" $*
\endtt

assuming that your personal {\GAP} `pkg' directory is a  subdirectory  of
`gapstuff' in your home directory. Finally, to let the `pq' program  know
where {\GAP} is and also know where your `pkg' directory is that contains
{\ANUPQ}, set the environment variable `ANUPQ_GAP_EXEC' to  the  complete
(i.e. absolute) path of  your  `mygap'  script  (do  not  use  the  tilde
abbreviation), or at the `make' step that compiles `pq' do

%begintt
\){\kernttindent}make GAP=<absolute-path-of-mygap>
%endtt

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E
 occasionally have  limits  on  what  may  be
written there. `ANUPQDirectoryTemporary' permits the  user  to  choose  a
directory (object) where one is not so limited.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Setting the Verbosity of ANUPQ via Info and InfoANUPQ}

\>`InfoANUPQ' V

The input to and the output from the `pq' program  is,  by  default,  not
displayed. However the user may choose to  see  some,  or  all,  of  this
input/output.   This   is   done   via   the   `Info'   mechanism    (see
Chapter~"ref:Info Functions" in the {\GAP} Reference  Manual).  For  this
purpose, there is the <InfoClass>  `InfoANUPQ'.  If  the  `InfoLevel'  of
`InfoANUPQ' is high enough each line of `pq' input/output is directed  to
a call to `Info' and will be displayed for the user to see.  By  default,
the `InfoLevel' of `InfoANUPQ' is 1, and it is recommended that you leave
it at this level, or higher. Messages that  the  user  should  presumably
want to see and output from the `pq' program influenced by the  value  of
the option `OutputLevel' (see the options listed in Section~"Pq"),  other
than timing and memory usage are directed to `Info' at `InfoANUPQ'  level
1.

To turn off *all* `InfoANUPQ' messaging, set the `InfoANUPQ' level to 0.

There are five other user-intended `InfoANUPQ' levels: 2, 3, 4, 5 and 6.

\beginexample
gap> SetInfoLevel(InfoANUPQ, 2);
\endexample

enables the display of most timing and memory usage data  from  the  `pq'
program, and also the number of identity instances when the  `Identities'
option is used. (Some timing and memory  usage  data,  particularly  when
profuse in quantity, is `Info'-ed at `InfoANUPQ' level 3  instead.)  Note
that the the {\GAP} functions `time' and `Runtime' (see~"ref:Runtime"  in
the {\GAP} Reference Manual) count the time spent by {\GAP} and *not* the
time spent by the (external) `pq' program.

\beginexample
gap> SetInfoLevel(InfoANUPQ, 3);
\endexample

enables the display of output of the nature of the first two  `InfoANUPQ'
that was not directly invoked by the  user  (e.g.~some  commands  require
{\GAP} to discover something about the current state known  to  the  `pq'
program). The identity instances processed under the `Identities'  option
are also displayed at  this  level.  In  some  cases,  the  `pq'  program
produces a  lot  of  output  despite  the  fact  that  the  `OutputLevel'
(see~"option OutputLevel") is unset or is set to 0; such output  is  also
`Info'-ed at `InfoANUPQ' level 3.

\beginexample
gap> SetInfoLevel(InfoANUPQ, 4);
\endexample

enables the display of all the commands  directed  to  the  `pq'  program,
behind a ```ToPQ> ''' prompt (so that you can  distinguish  it  from  the
output from the `pq' program). See Section~"Hints and Warnings  regarding
the use of  Options"  for  an  example  of  how  this  can  be  a  useful
troubleshooting tool.

\beginexample
gap> SetInfoLevel(InfoANUPQ, 5);
\endexample

enables the display of the `pq' program's prompts for input. Finally,

\beginexample
gap> SetInfoLevel(InfoANUPQ, 6);
\endexample

enables the display of all other output from the `pq' program, namely  the
banner and menus. However, the timing data printed when the  `pq'  program
exits can never be observed.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Utility Functions}

\>PqLeftNormComm( <elts> ) F

returns for a list of elements of some group (e.g.~<elts> may be  a  list
of words in the generators of  a  free  or  fp  group)  the  left  normed
commutator of <elts>, e.g.~if <w1>, <w2>, <w3>  are  such  elements  then
`PqLeftNormComm( [<w1>, <w2>, <w3>] );' is  equivalent  to  `Comm(  Comm(
<w1>, <w2> ), <w3> );'.

*Note:* <elts> must contain at least two elements.

\>PqGAPRelators( <group>, <rels> ) F

returns a list of words that {\GAP} understands, given a list  <rels>  of
strings in the string representations of the generators