The GAP 4 package `Polenta'
========================

 
This package provides functions for  computation with matrix
groups. Let $G$ be a subgroup of $GL(d,R)$ where the ring $R$ is
either equal to $\Q,\Z$ or a finite field $\F_q$.
Then:
   - We can test whether $G$ is solvable.
   - We can test whether $G$ is polycyclic.
   - If $G$ is polycyclic, then we can determine a polycyclic
    presentation for $G$.
    
A group $G$ which is given by a polycyclic presentations can be largely
investigated by algorithms implemented in the GAP-package
Polycyclic. For example
we can determine if $G$ is torsion-free
and calculate the torsion subgroup. Further we can compute the derived
series and the Hirschlength of the group $G$. Also various methods for
computations with subgroups, factorsgroups and extensions are
available.
 
As a by-product, the Polenta package
provides some functionality to compute certain module series for
modules of solvable groups. For example, if
$G$ is a rational polycyclic matrix group, then we can compute the
radical series of the natural
$\Q[G]$-module $\Q^d$.

 
Installing this package
=======================

The Polenta package is part of the standard distribution of GAP and
so normally there should be no need to install it separately.

If by any chance it is not part of your GAP distribution, then 
this package is available at
        
     www.gap-system.org/Packages/packages.html
                                                                           
in form of a gzipped tar-archive and as an uncompressed tar-archive.
The standard method is to unpack the package into the `pkg'
directory  of your GAP distribution.  This will create a `polenta'
subdirectory. 
For other non-standard options please see  Chapter 74.1 
in the GAP Reference Manual.

Note that the GAP-Packages Alnuth and Polycyclic are needed for this package.
Normally they should be contained in your distribution. If not 
they can be obtained at

      http://www.gap-system.org/Packages/packages.html


Getting and installing KASH
===========================
                    
Note that the GAP package Alnuth whose functionality is used by the Polenta
package requires the installation of KANT respectively
KASH, the shell
of the computational algebraic number theory system KANT.  KASH itself
is not part of the Alnuth package.  It has to be obtained and installed
independently.
                                                            
KASH is available at

               www.math.tu-berlin.de/~kant/download.html

Note that you have to download two files for a complete installation
of KASH. To install  version 2.4 of KASH on a Linux
system you should do the following:

 1. Download the files
    kash_2.4.common.tar.gz and kash_2.4.1.linux.tar.gz
    into the same directory on your system.
                                                                               
 2. Unpack the files using tar.  This will create a directory
    KASH_2.4 containing, amongst other files, the KASH executable called
    kash.  The place where KASH is put is independent of the place
    where the Alnuth or Polenta package is installed.
 


Loading the Polenta package
==========================

If the  Package is not already loaded 
then you have to request it explicitly. 
This  can be 
done by `LoadPackage("polenta")'.
The `LoadPackage' command is described in Section 72.2.1
in the GAP Reference Manual.


Running the test suite
======================

Once the package is installed, it is possible to check the correct
installation by running the test suite of the package.

    gap> ReadPackage( "Polenta", "tst/testall.g" );

For more details on  Test Files see 
Section 7.9 of the 
GAP Reference Manual.

If the test suite runs into an error, even though the packages
Polycyclic and 
Alnuth  and  the computational algebraic number theory system KANT
have been correctly installed, then please send a message
to `BjoernAssmann@gmx.net' including the error message.
   
                                 
Author
======
 
The Polenta package was written by:
 
  Bjoern Assmann, 
  Mathematical Institute
  University of St. Andrews
  North Haugh
  St. Andrews
  Fife
  KY16 9SS
  Scotland, UK
  e-mail: BjoernAssmann@gmx.net