% This file was created automatically from gptransv.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  gptransv.msk               GAP documentation               Gene Cooperman
%A							     and Scott Murray
%%
%A  @(#)$Id: gptransv.msk,v 1.6 2002/04/15 10:02:28 sal Exp $
%%
%Y  (C) 2000 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\PreliminaryChapter{Transversals of subgroups}

This chapter describes the category of transversals of subgroups.
This category has the following representations:  
`TransvBySchreierTree', `TransvByHomomorphism',
`TransvByDirProd', `TransvByTrivSubgrp', `TransvBySiftFunct'.



*The functions and operations described in this chapter have been added
very recently and are still undergoing development. It is conceivable that
names of variants of the functionality might change in future versions. If
you plan to use these functions in your own code, please contact us.*

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{General operations on transversals}

Every kind of transversal has the following common operations/attributes:
`Size',    `Enumerator',    `Iterator',    `Random',    `TransversalElt',
`SiftOneLevel'.



\>TransversalElt( <ss>, <elt> ) O

for a transversal <ss> and group element <elt>,
returns the representative of the coset containing the element <elt>.
The representative is unique, i.e. `TransversalElt' will return the
same thing for different elements of the same coset.


\>SiftOneLevel( <ss>, <g> )!{for subgroup transversals} O

For a transversal <ss> and group element <g>, the following
relationship with `TransversalElt' (see~"TransversalElt") defines
`SiftOneLevel':

\){\kernttindent}SiftOneLevel(<ss>, <g>) = <g> * TransversalElt(<ss>, <g>)

For some kinds of transversal `TransversalElt' is more efficient,
for others `SiftOneLevel' is.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Transversals by Schreier tree}

For transversals of stabiliser subgroups, we store  a  Schreier  tree  to
allow us to find transversal elements.

*Note:* `SiftOneLevel' is more efficient that `TransversalElt'.

Transversals can be extended as more generators are found for the
stabiliser.
Orbit generators are generators for the original group, stored separately
so we can add extra generators to form a shallower tree.
Orbits are stored as hash tables.



\>SchreierTransversal( <basePoint>, <Action>, <strongGens> ) F

creates a transversal by Schreier tree for the subgroup stabilising
the point <basePoint> (an object, typically an integer or vector) 
inside the group generated by <strongGens> (a list of strong generators
for the group).
This is the only correct way to create a transversal by Schreier 
tree.


\>OrbitGenerators( <ss> ) O

The elements used to compute the orbit <ss>.  These will be generators for 
the larger group, however there will often be redundancies to keep the 
Schreier tree shallow.


\>OrbitGeneratorsInv( <ss> ) O

Inverses of the orbit generators of the orbit <ss>.


\>BasePointOfSchreierTransversal( <ss> ) O

The base point of transversal by Schreier tree <ss>, i.e. the point
stabilised.


\>One( <ss> ) A

The identity of group <ss>.


\>ExtendSchreierTransversal( <st>, <newGens> ) F
\>ExtendSchreierTransversal( <st>, <newGens>, <newGensInv> ) F

Extend a transversal by Schreier tree <st> with new generators <newGens>.


\>ExtendSchreierTransversalShortCube( <ss>, <newGens> ) F
\>ExtendSchreierTransversalShortCube( <ss>, <newGens>, <newGensInv> ) F

gdc - Ideally, `ExtendSchreierTransversal' should be a field
      of the Schreier tree, chosen by `SchreierTransversal()'.

gdc - This is the new function with the cube control tree.

EXPERIMENTAL IDEA:  IT WOULD NEED TO BE TUNED.  NOT CURRENTLY
COMPETITIVE WITH METHOD BELOW.


\>ExtendSchreierTransversalShortTree( <ss>, <newGens> ) F
\>ExtendSchreierTransversalShortTree( <ss>, <newGens>, <newGensInv> ) F

gdc - This is the original function with the traditional control tree

BASED ON: \cite{CF94}
 ``A Random Base Change Algorithm for Permutation Groups'', G.~Cooperman
 and L.~Finkelstein, J. of Symbolic Computation 17, 1994,
 pp.~513--528


\>CompleteSchreierTransversal( <ss> ) F

Complete the transversal.  In order to ensure that the Schreier tree does
not become too deep, the `Extend...' functions do not complete the
transversal.  Rather they extend it by depth one.


\>PreferredGenerators( <ss> ) A

returns the preferred generators of the transversal by Schreier tree <ss>.
The preferred generators are always 
used first when computing the Schreier tree.


\>SchreierTreeDepth( <ss> ) F

The depth of Schreier tree <ss>.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Transversals by homomorphic images}

For the transversal of the kernel of a homomorphism,
a quotient group for the kernel of a homomorphism is stored.
Transversal elements are computed by finding a chain for the image group
and doing shadowed stripping.

*Note:* `TransversalElt' is more efficient that `SiftOneLevel'.



\>HomTransversal( <h> ) F

creates a hom transversal for the homomorphism <h>.


\>Homomorphism( <homtr> )!{for subgroup transversals} O

The homomorphism of hom transversal <homtr>.


\>QuotientGroup( <homtr> ) A

The quotient group of hom transversal <homtr>.


\>ImageGroup( <homtr> ) O

The image group of hom transversal <homtr>.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Transversals by direct products}

Stores projection and injection for a direct product.  
The chain subgroup is the kernel of the projection.



\>Projection( <dpt> ) O

The projection of the direct product transversal <dpt>.


\>Injection( <dpt> ) O

The injection of a direct product transversal <dpt>.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Transversals by Trivial subgroups}

For use when our group is small enough to enumerate.



\>TransversalByTrivial( <G> ) F

returns a transversal by trivial subgroup for the group <G>.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Transversals by sift functions}

Given a group, subgroup, and sift function from group to subgroup
    that is constant on cosets, this defines a transversal.
One typically prefers a normalized sift function that is the
    the identity map on subgroups.
For situations when there is a non-group theoretic method for 
computing the transversal element, e.g. using row reduction for
the stabiliser of an invariant subspace.                                 

*Note:* `SiftOneLevel' is more efficient than `TransversalElt'.



\>TransversalBySiftFunction( <supergroup>, <subgroup>, <sift> ) F

returns a transversal by sift function.



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

