<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %W  foa.tex                   GAP documentation            Heiko Theißen -->
<!-- %% -->
<!-- %% -->
<!-- %Y  Copyright 1997,  Lehrstuhl D für Mathematik,  RWTH Aachen,   Germany -->
<!-- %% -->
<Chapter Label="Function-Operation-Attribute Triples">
<Heading>Function-Operation-Attribute Triples</Heading>

&GAP;  is eager  to maintain information  that  it has gathered about an
object, possibly by lengthy  calculations. The most  important mechanism
for information maintenance  is the  automatic  storage and look-up  that
takes  place  for  <E>attributes</E>; and    this   was already mentioned   in
section&nbsp;<Ref Sect="Attributes" BookName="tut"/>.
In   this  chapter  we  will
describe further mechanisms that  allow storage of  results that  are not
values of attributes.
<P/>
<Index>FOA triples</Index>
The  idea which is   common to all  sections  is that certain operations,
which are  not themselves attributes, have  an attribute  associated with
them. To automatically delegate tasks to the  attribute, &GAP; knows, in
addition  to  the <E>operation</E>  and  the  <E>attributes</E>   also a
<E>function</E>, which  is  <Q>wrapped around</Q> the  other  two. This <Q>wrapper
function</Q>  is called by    the user and    decides whether to  call  the
operation    or  the    attribute     or  possibly     both.   The  whole
<E>f</E>unction-<E>o</E>peration-<E>a</E>ttribute triple (or <E>FOA triple</E>)  is set up by
a single   &GAP; command which  writes the  wrapper function and already
installs  some methods,  e.g.,  for the attribute  to   fall back on  the
operation. The idea  is then that subsequent  methods, which  perform the
actual computation, are installed   only for the operation,   whereas the
wrapper function remains unaltered, and  in general no additional methods
for the attribute are required either.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Key Dependent Operations">
<Heading>Key Dependent Operations</Heading>

<#Include Label="KeyDependentOperation">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="In Parent Attributes">
<Heading>In Parent Attributes</Heading>

<#Include Label="InParentFOA">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Operation Functions">
<Heading>Operation Functions</Heading>

<Index Key="ExternalSet" Subkey="computing orbits"><C>ExternalSet</C></Index>
<Index Key="G-sets" Subkey="computing orbits"><M>G</M>-sets</Index>
<Index Key="Orbits" Subkey="as attributes for external sets"><C>Orbits</C></Index>
Chapter&nbsp;<Ref Chap="Group Actions"/>
and, in particular,
the Section&nbsp;<Ref Sect="About Group Actions"/>
<!-- % currently in <C>abattoir/group.tex</C>, <C>abattoir/permgrp.tex</C>, -->
<!-- % <C>abattoir/solvgrp.tex</C> ... -->
explain that certain operations such as <Ref Sect="Orbits"/>),
besides their usual usage with arguments <A>G</A>, <A>D</A>, and <A>opr</A>,
can also be applied to an external set (<M>G</M>-set),
in which case they can be interpreted as attributes.
Moreover, they can also be interpreted as attributes for permutation
groups, meaning the natural action on the set of its moved points.
<P/>
The definition of <Ref Sect="Orbits"/> says that a method
should be a function
with arguments <A>G</A>, <A>D</A>, <A>gens</A>, <A>oprs</A>, and <A>opr</A>,
as in the case of the operation <Ref Oper="ExternalSet"/>
when specified via <A>gens</A> and <A>oprs</A>
(see&nbsp;<Ref Sect="External Sets"/>).
All other syntax variants allowed for <Ref Sect="Orbits"/>
(e.g., leaving out <A>gens</A> and <A>oprs</A>)
are handled by default methods.
<P/>
The default methods for <Ref Sect="Orbits"/> support the
following behaviour.
<Enum>
<Item>
    If the only argument is an external set <A>xset</A> and the attribute
    tester <C>HasOrbits( <A>xset</A> )</C> returns <K>true</K>,
    the stored value of that attribute is returned.
</Item>
<Item>
    If the only argument is an external set <A>xset</A> and the attribute
    value is not known,
    the default arguments are obtained from the data of <A>xset</A>.
</Item>
<Item>
    If <A>gens</A> and <A>oprs</A> are not specified,
    <A>gens</A> is set to <C>Pcgs( <A>G</A> )</C>
    if <C>CanEasilyComputePcgs( <A>G</A> )</C>
    is <K>true</K>, and to <C>GeneratorsOfGroup( <A>G</A> )</C> otherwise;
    <A>oprs</A> is set to <A>gens</A>.
</Item>
<Item>
    The default value of <A>opr</A> is <Ref Func="OnPoints"/>.
</Item>
<Item>
    In the case of an operation of a permutation group <A>G</A>
    on <C>MovedPoints( <A>G</A> )</C> via
    <Ref Func="OnPoints"/>,
    if the attribute tester <C>HasOrbits( <A>G</A> )</C> returns <K>true</K>,
    the stored attribute value is returned.
</Item>
<Item>
    The operation is called as
    <C><A>result</A>:= Orbits( <A>G</A>, <A>D</A>, <A>gens</A>,
    <A>oprs</A>, <A>opr</A> )</C>.
</Item>
<Item>
    In the case of an external set <A>xset</A> or a permutation group
    <A>G</A> in its natural action,
    the attribute setter is called to store <A>result</A>.
</Item>
<Item>
    <A>result</A> is returned.
</Item>
</Enum>
<P/>
The declaration of operations that match the above pattern is done
as follows.

<#Include Label="OrbitsishOperation">
<#Include Label="OrbitishFO">

<Subsection Label="Example: Orbit and OrbitOp">
<Heading>Example: Orbit and OrbitOp</Heading>

For example, to setup the function <Ref Oper="Orbit"/>
and its operation <C>OrbitOp</C>,
the declaration file <F>lib/oprt.gd</F> contains the following line of code:
<Log><![CDATA[
OrbitishFO( "Orbit", OrbitishReq, IsCollsElms, false, false );
]]></Log>
The variable <C>OrbitishReq</C> contains the standard requirements
<Log><![CDATA[
OrbitishReq  := [ IsGroup, IsList, IsObject,
                  IsList,
                  IsList,
                  IsFunction ];
]]></Log>
which are usually entered in calls to <Ref Func="OrbitishFO"/>.
<P/>
The relation test via <A>famrel</A> is used to provide a uniform
construction of the wrapper functions created by
<Ref Func="OrbitishFO"/>,
in spite of the different syntax of the specific functions.
For example, <Ref Oper="Orbit"/> admits the calls
<C>Orbit( <A>G</A>, <A>D</A>, <A>pnt</A>, <A>opr</A> )</C>
and <C>Orbit( <A>G</A>, <A>pnt</A>, <A>opr</A> )</C>,
i.e., the second argument <A>D</A> may be omitted;
<Ref Oper="Blocks" Label="for a group, an action domain, etc."/>
admits the calls
<C>Blocks( <A>G</A>, <A>D</A>, <A>seed</A>, <A>opr</A> )</C> and
<C>Blocks( <A>G</A>, <A>D</A>, <A>opr</A> )</C>,
i.e., the third argument may be omitted.
The translation to the appropriate call of <C>OrbitOp</C> or
<C>BlocksOp</C>,
for either operation with five or six arguments,
is handled via <A>famrel</A>.
<P/>
As a  consequence, there must not only be methods for <C>OrbitOp</C>
with the six arguments corresponding to <C>OrbitishReq</C>,
but also methods for only five arguments (i.e., without <A>D</A>).
Plenty of examples are contained in the implementation file
<F>lib/oprt.gi</F>.
<P/>
In order to handle a few special cases
(currently <Ref Oper="Blocks" Label="for a group, an action domain, etc."/>
and
<Ref Oper="MaximalBlocks" Label="for a group, an action domain, etc."/>),
also the following form of <Ref Func="OrbitishFO"/> is supported.
<P/>
<C>OrbitishFO( <A>name</A>, <A>reqs</A>, <A>famrel</A>, <A>attr</A> )</C>
<P/>
The functions in question depend upon an argument <A>seed</A>,
so they cannot be regarded as attributes.
However, they are most often called without giving <A>seed</A>,
meaning <Q>choose any minimal resp. maximal block system</Q>.
In this case, the result can be stored as the value of the attribute
<A>attr</A> that was entered as fourth argument of
<Ref Func="OrbitishFO"/>.
This attribute is considered by a call
<C>Blocks( <A>G</A>, <A>D</A>, <A>opr</A> )</C>
(i.e., without <A>seed</A>) in the same way as
<Ref Attr="Orbits" Label="attribute"/> considers <C>OrbitsAttr</C>.
<P/>
To set this up,
the declaration file <F>lib/oprt.gd</F> contains the following lines:
<Log><![CDATA[
DeclareAttribute( "BlocksAttr", IsExternalSet );
OrbitishFO( "Blocks",
    [ IsGroup, IsList, IsList,
      IsList,
      IsList,
      IsFunction ], IsIdenticalObj, BlocksAttr, true );
]]></Log>
And this extraordinary FOA triple works as follows:
<Example><![CDATA[
gap> s4 := Group((1,2,3,4),(1,2));;
gap> Blocks( s4, MovedPoints(s4), [1,2] );
[ [ 1, 2, 3, 4 ] ]
gap> Tester( BlocksAttr )( s4 );
false
gap> Blocks( s4, MovedPoints(s4) );
[ [ 1, 2, 3, 4 ] ]
gap> Tester( BlocksAttr )( s4 );  BlocksAttr( s4 );
true
[ [ 1, 2, 3, 4 ] ]
]]></Example>

</Subsection>
</Section>
</Chapter>


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