<!-- 

  intro.xml            orb package documentation
                                                               Juergen Mueller
                                                               Max Neunhoeffer
                                                                  Felix Noeske

         Copyright (C) 2005-2008 by the authors

This chapter gives a short introduction and explains the philosophy
behind the package.

-->

<Chapter Label="intro">
<Heading>Introduction</Heading>

<Section Label="philosophy">
<Heading>Motivation for this package</Heading>

This package is about orbit enumeration. It bundles fundamental
algorithms for orbit enumeration as well as more sophisticated
special-purpose algorithms for very large orbits.

<P/>
The fundamental methods are basically an alternative implementation to
the orbit algorithms in the &GAP; library. We tried to make them more
flexible and more efficient at the same time, therefore backwards
compatibility with respect to the user interface had to be given up.
In addition, more information about how an orbit was produced is
retained and is available for further usage. These orbit enumeration
algorithms build on even more fundamental code for hash tables.

<P/>
The higher level algorithms basically implement the idea to enumerate
an orbit <Q>by suborbits</Q> with respect to one or more subgroups.
While these orbit-by-suborbit algorithms are much more efficient in
many cases, they very often need careful and sometimes difficult
preparations by the user. They are definitely not intended to be
<Q>push-the-button-tools</Q> but require a considerable amount of
knowledge from the <Q>pilot</Q>.

<P/>
Quite a bit of the code in this package consists in fact of
interactive tools to enable users to prepare the data for the
orbit-by-suborbit algorithms to work.
</Section>

<Section Label="overview">
<Heading>Overview over this manual</Heading>

Chapter <Ref Chap="install"/> describes the installation of this package.
Chapter <Ref Chap="basic"/> describes our reimplementation of the basic 
orbit algorithm. Chapter <Ref Chap="hash"/> describes our
toolbox for hash tables, Chapter <Ref Chap="cache"/> explains
caching data structures, whereas Chapter <Ref Chap="avl"/> describes
our implementation of AVL trees. Chapter <Ref Chap="random"/> covers
tools to use random methods in groups. Chapter <Ref Chap="search"/>
describes a lot of tools to search in groups and orbits. These
techniques are basically intended to provide the data structures
necessary to run the code described in Chapter <Ref
    Chap="bysuborbit"/> to use the orbit-by-suborbit algorithms.
Currently, Chapter <Ref Chap="quotfinder"/> is an empty placeholder.
In some future version of this package it will contain a description
of code which helps users to find nice quotients of modules which is
also needed for the orbit-by-suborbit algorithms. However, since the
interface to this code is not yet stable, we chose not to document it
as of now, in particular because it relies on other not yet published
packages as of the time of this writing.
Finally, Chapter <Ref Chap="examples"/>
shows an instructive examples for the more sophisticated 
usage of this package.
</Section>

<Section Label="feedback">
<Heading>Feedback</Heading>

For bug reports, feature requests and suggestions, please use our
<URL Text="issue tracker">https://github.com/gap-packages/orb/issues</URL>.

</Section>

<!-- ############################################################ -->

</Chapter>
