<!-- %W  example.xml         Ferret documentation        Christopher Jefferson -->
<!-- %H                                                                        -->
<!-- %Y  Copyright (C) 2014, School of Comp. Sci., St Andrews, Scotland        -->


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="The Ferret Package">
<Heading>The Ferret Package</Heading>

<Index>Ferret package</Index>
This chapter describes the &GAP; package Ferret. Ferret implements highly efficient
implementations of a range of search algorithms on permutation groups.


If you are interested in if Ferret can be applied to another problem, please contact the authors, who will be happy to look into if your problem can be solved with Ferret.



<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Replacing Built-in functionality">
<Heading>Replacing Built-in functionality</Heading>

Ferret automatically installs methods which replace GAP's a number of GAP's built-in functionality:

<List>
    <Item>
        <Emph>Intersection</Emph> for a list of permutation groups.
    </Item>
    <Item>
        <Emph>Stabilizer(G,S,Action)</Emph> for a permutation group G, and the actions:
        <List>
            <Item><C>OnSets</C></Item>
            <Item><C>OnOnSets</C></Item>
            <Item><C>OnSetsDisjointSets</C></Item>
            <Item><C>OnSetsSets</C></Item>
            <Item><C>OnTuples</C></Item>
            <Item><C>OnPairs</C></Item>
            <Item><C>OnDirectedGraph</C></Item>
        </List>
    </Item>
    <Item>
        <Emph>Stabilizer(G, S)</Emph> for a permutation group G and a:
        <List>
            <Item>permutation</Item>
            <Item>transformation</Item>
            <Item>partial permutation</Item>
        </List>
    </Item>
</List>

If you would like to disable this functionality, you can use <Ref Label="EnableFerretOverloads"/>.

<#Include Label="EnableFerretOverloads">
<#Include Label="FerretOverloadsEnabled">

</Section>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Using 'Solve' to solve problems directly">
<Heading>Using 'Solve' to solve problems directly</Heading>

The main method of using Ferret's functionality is the <Ref Func="Solve"/> method. This method
intersects a list of permutation groups.

The unusual feature is that these permutation groups can be represented in a variety of ways.
They can be usual GAP permutation groups given as a list of generators, or they can be the group
which is the stabilizer of combinatorial object under some action.

Larger problems are then composed from these pieces. For example, the stabilizer of a set S under
a group G can be expressed as the intersection of the group which stabilizes the set S and the group G.

For this problem, there would be no point using <Ref Func="Solve"/>, as GAP's built in 'Stabilizer' function provides the same functionality. However, with <Ref Func="Solve"/> we can intersect any number of groups at the same time, for example finding the intersection of two
groups G and H, the stabilizer of a set S and the stabilizer of a set of sets T, with the following code:

<Log>
gap> Solve([ConInGroup(G), ConInGroup(H), 
> ConStabilize(S, OnSets), ConStabilize(T, OnSetSets)])
</Log>

The currently allowed arguments to <Ref Func="Solve"/> are:

<List>
    <Item>
        <Ref Func="ConInGroup"/>, which represents a Permutation Group in GAP
    </Item>
    <Item>
        <Ref Func="ConStabilize" Label="for an object and an action"/>, which takes an object and an action.
    </Item>
</List>


</Section>

</Chapter>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %E -->

