#######################################################################
#
#      SISYPHOS - Computing in modular group algebras of p-groups
#                                   
#                             Version 0.5
#                                   
#                           Martin Wursthorn
#                Mathematisches Institut B, 3.Lehrstuhl
#                        Universitaet Stuttgart
#
#######################################################################

1. Introduction

SISYPHOS is a program package developped to compute with p-groups and 
their modular group algebras. It originated in an implementation of an 
algorithm by Roggenkamp, Scott and the author to test such group 
algebras for isomorphisms. This algorithm has been modified and 
improved to be applicable to p-groups as well. The following features 
are incorporated in the current implementation:

features dealing with modular group algebras of p-groups:
     Symbolic computations with elements,
     computation of centre, centralizers, lie ideals,
     computing with subspaces and ideals,
     isomorphism tests for such group algebras,
     computation of a polycyclic presentation of the normalized units 
     group,
     
features dealing with p-groups:
     (outer) automorphisms of polycyclically presented p-groups,
     isomorphisms between two polycyclically presented groups or a 
     freely presented and a polycyclically presented group,
     tests for isomorphisms between two polycyclically presented groups 
     or a freely presented and a polycyclically presented group,
     several output formats are supported (generators, element lists, 
     polycyclic presentations for normalized automorphism groups)
     
The package can be used either as a GAP shared library via a special 
interface that allows the program to be called from within GAP by 
special GAP functions (see GAP documentation) or as a standalone 
program with its own user interface. The first possibility only allows 
access to the routines dealing with p-groups, but has the advantage that 
the results can be processed by GAP without any conversions. The second 
possibility gives access to all features of SISYPHOS, but though it is 
still possible to have some of the routines produce output in a GAP 
compatible format, you will have to reformat the output in general to 
resue it in some other computer algebra package. 

Like GAP, the standalone version of SISYPHOS is an interactive system 
controlled by a command language. this command language, called 'Lapidar' 
is rather simple and does not yet support any structures that alter the 
flow of control, like branching instructions and loops. This language 
is described in the SISYPHOS manual. 

The following instructions refer to the standalone version only. If you 
want to install SISYPHOS as GAP shared library, follow the instructions 
in the GAP manual.


2. Implementation

SISYPHOS is written in ANSI-C and should run on every UNIX system (and
some non-UNIX systems) that provides an ANSI-C compiler (e.g. GNU cc).
Compilers keeping to the old C standard will not be able to compile the
sources. 

Up to now SISYPHOS has been ported by myself to the following platforms:

     IBM RS6000 under AIX 3.2, native compiler,
     HP9000 73x under HP-UX 8.0/9.0, native compiler,
     PC386/486 under Linux, GNU C,
     PC386/486 under DOS or OS/2, emx,
     ATARI ST/TT under TOS, GNU C,
     ATARI ST/TT under TOS, PureC
     
There implementations on  several other platforms by other people.


3. Getting the sources

The sources for SISYPHOS, several group libraries and additional 
programs are available via anonymous ftp from the machine

     'darfnix.mathematik.uni-stuttgart.de'   (129.69.116.154)

In the directory 'pub/sisyphos' on this machine there is a compressed 
tar-file 

     'sisyphos.x.y.z.tar.Z'

which contains the complete package. 'x.y.z' denotes the version number,
make sure you get the archive with the highest number, since the directory
may  contain also older versions. If you have already installed a former
version of SISYPHOS there may the possibility to upgrade this version using
the files 'sis.x1.y1.z1-x2.y2.z2.patch', if there are such files (for major
upgrades this will not be the case). These are input files for the 'patch'
program that upgrade the sources from version 'x1.y1.z1' to 'x2.y2.z2'.
You may have to apply several of these patch files to upgrade your system
to the actual version level.


4. Installation

Before you extract the sources you should create a directory which will 
take up the complete package and move the SISYPHOS archive file into 
this directory. This applies also to the patch files you may need. 
In the sequel I will refer to this directory as the SISYPHOS-directory
and call it 'sis' in the examples though its name is arbitrary. 
SISYPHOS must know about the location of this directory in order to find 
the libraries and to know where to put intermediate files. This can be 
accomplished in two ways:

a) Define an environment variable called 'SISLIB' that points to the 
     SISYPHOS-directory, e.g. by the commands
     
     'export SISLIB=$HOME/sis/' (sh,ksh,bash etc.) or 
     'setenv SISLIB $HOME/sis/' (csh,tcsh).

b) Create a shell script for the invocation of SISYPHOS that calls 
     the program with the '-l' option specifying the correct path. This 
     script could look like
     
     #!/bin/sh
     exec /usr/local/sis/src/sis -l /usr/local/sis/ $*

Note the trailing '/' in the specification of the path! 

After this preparations you are ready to extract the archive by a command 
like

     'zcat sisyphos.0.5.1.tar.Z | tar xpvf -'   (standard tar) or
     'tar zpxvf sisyphos.0.5.1.tar.Z'            (GNU tar).

This will create the following subdirectories

'src':
     contains all the C source files of SISYPHOS along with the test 
     script and a file with the correct output of the test script.
     
'doc':
     the SISYPHOS manual as TeX '.dvi' file and as postscript file 
     with exitension '.ps'. 
     
'ideal':
     is the directory for the intermediate files generated by the 'lift'
      command. (Consult the manual for details)
     
'groups':
     is the library directory containing files with presentations for 
     p-groups.

Now cd to the 'src' directory and execute 'make'. You will see a list of
machine - operating system - compiler configurations for which the 
installation of SISYPHOS can be done almost automatically. This means
that you simply
have to type

     'make <target>',

where '<target>' is one of the three -- part entries in the list to
create an executable image of SISYPHOS provided there is a '<target>' 
in the list that reflects your local setup. Currently the following 
configurations are supported directly:

'hp700-hpux-gcc2'   - for HP9000/7xx machines under HP--UX with GNU cc 2,
'hp700-hpux-cc'     - for HP9000/7xx machines under HP--UX with cc,
'ibm6000-aix-cc'    - for IBM RS6000 under AIX 3.x with cc,
'ibmpc-linux-gcc2'  - for IBM 386/486 PCs under Linux with GNU cc 2,
'ibmpc-emx-gcc2'    - for IBM 386/486 PCs under DOS or OS/2 with emx,
'generic-unix-gcc2' - for other UNIX machines with GNU cc 2

For most machines with the GNU compiler installed the last target 
should work. If you do not have GNU C but your native C compiler is 
ANSI--compatible you should try to use the last target. As mentioned above, 
SISYPHOS also runs on some non-UNIX machines (ATARI ST/TT, PC 386/486 
under DOS or OS/2). For these machines the executable image will be 
distributed and can be obtained from the same place as the sources. It 
should be copied into the 'src' directory.
After the installation and the tests however you can remove the contents
of the 'src' subdirectory on those machines except the executable itself.

In any case an executable image named 'sis' ( or 'sis.exe' or 'sis.ttp' )
will have been created in the 'src'-directory. At this point you should 
test the program. The distribution contains a test script 'testsis' that 
you should execute by simply typing its name.  It will perform some 
calculations and compare the results to the correct ones in the file 
'testsis.out'. Apart from differing informations about the memory used by 
SISYPHOS there should be no further output from 'testsis'. 
Note however that this will work only on UNIX machines! If it passes 
this test you may want to make the system publicly accessible. The best 
way to do this is to create a shell script as described at the beginning of  
this section and 
install this script in a directory where executables on your machine 
are kept like '/usr/bin' or '/usr/local/bin'. You will need superuser 
priviledge to do this.

Furthermore you should produce a printed copy of the manual using one 
of the supplied files in the 'doc' subdirectory. How this can be 
accomplished is site dependent. 


5. Contact address

In any case of difficulties whether with the installation or the usage of 
SISYPHOS, especially if you encounter any bugs send an email to the
following address

     'pluto@machnix.mathematik.uni-stuttgart.de'

It is very helpful if you include a copy of the input that produced the
bug and the (erroneous) output of SISYPHOS. Moreover any form of
constructive criticism is welcome. The program in its current state is
by no means finished but is developped further permanently.



Martin Wursthorn
Mathematisches Institut B
3. Lehrstuhl
Universitaet Stuttgart
70550 Stuttgart

Tel.: +49 (0)711 685 5517
Fax.: +49 (0)711 685 5322

