<!-- % This file was created automatically from intrfc.msk. -->
<!-- % DO NOT EDIT! -->
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %W  intrfc.msk              GAP manual                   Alexander Hulpke -->
<!-- %W                                                       Andrew Solomon -->
<!-- %% -->
<!-- %H  @(#)<M>Id: intrfc.msk,v 1.12 2002/10/02 12:12:00 gap Exp </M> -->
<!-- %% -->

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Chapter Label="Examples of Extending the System">
<Heading>Examples of Extending the System</Heading>

This chapter gives a few examples of how one can extend the functionality of
&GAP;.
<P/>
They are arranged in ascending difficulty. We show how to install new
methods, add new operations and attributes and how to implement new features
using categories and representations.  (As we do not introduce completely
new kinds of objects in these example it will not be necessary to declare
any families.)
Finally we show a simple way how to create new objects with an own
arithmetic.
<P/>
The examples given are all very rudimentary &ndash; no particular error checks
are performed and the user interface sometimes is quite clumsy. These examples
may be constructed for presentation purposes only and they do not necessarily
constitute parts of the &GAP; library.
<P/>

Even more complex examples that create whole classes of objects anew will be
given in the following two chapters <Ref Chap="An Example -- Residue Class Rings"/> and
<Ref Chap="An Example -- Designing Arithmetic Operations"/>.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Addition of a Method">
<Heading>Addition of a Method</Heading>

The easiest case is the addition of a new algorithm as a method for an
existing operation for the existing structures.
<P/>
For example, assume we wanted to implement a better method for computing the
exponent of a nilpotent group (it is the product of the exponents of the
Sylow subgroups).
<P/>
The first task is to find which operation is used by &GAP;
(it is <Ref Func="Exponent"/>) and how it is declared.
We can find this in the Reference Manual (in our particular case
in section&nbsp;<Ref Sect="Numerical Group Attributes"/>)
and the declaration in the library file <F>lib/grp.gd</F>.
The easiest way to find the place of the declaration is usually to
<C>grep</C> over all <C>.gd</C> and <C>.g</C> files,
see section&nbsp;<Ref Chap="Library Files"/>.
<P/>
In our example the declaration in the library is:
<Log><![CDATA[
DeclareAttribute("Exponent",IsGroup);
]]></Log>
<P/>
Similarly we find that the filter
<Ref Func="IsNilpotentGroup"/> 
represents the concept of being nilpotent.
<P/>
We then write a function that implements the new algorithm which takes the
right set of arguments and install it as a method. In our example this
installation would be:
<Log><![CDATA[
InstallMethod(Exponent,"for nilpotent groups",
  [IsGroup and IsNilpotent],
function(G)
  [function body omitted]
end);
]]></Log>
<P/>
We have left out the optional rank argument of <Ref Func="InstallMethod"/>,
which normally is a wise choice
&ndash;&GAP; automatically uses an internal ranking based on the filters
that is only offset by the given rank.
So our method will certainly be regarded as <Q>better</Q> than
a method that has been installed for mere groups or for solvable groups but
will be ranked lower than the library method for abelian groups.
<P/>
That's all.
Using <Ref Sect="ApplicableMethod"/> we can
check for a nilpotent group that indeed our new method will be used.
<P/>
When testing, remember that the method selection will not check for
properties that are not known. (This is done internally by checking the
property tester first.) Therefore the method would not be applicable
for the group <C>g</C> in the following definition but only for the
&ndash;mathematically identical but endowed with more knowledge by &GAP;&ndash;
group <C>h</C>.
(Section&nbsp;<Ref Sect="Enforcing Property Tests"/> shows a way around this.)
<P/>
<Example><![CDATA[
gap> g:=Group((1,2),(1,3)(2,4));;
gap> h:=Group((1,2),(1,3)(2,4));;
gap> IsNilpotentGroup(h); # enforce test
true
gap> HasIsNilpotentGroup(g);
false
gap> HasIsNilpotentGroup(h);
true
]]></Example>
<P/>
Let's now look at a slightly more complicated example:
We want to implement a better method for computing 
normalizers in a nilpotent permutation group.
(Such an algorithm can be found for example in
<Cite Key="luksrakocziwright97"/>.)
<P/>
We already know <Ref Func="IsNilpotentGroup"/>,
the filter <Ref Func="IsPermGroup"/> 
represents the concept of being a group of permutations.
<P/>
&GAP; uses <Ref Func="Normalizer" Label="for two groups"/>
to compute normalizers,
however the declaration is a bit more complicated.
In the library we find
<P/>
<Log><![CDATA[
InParentFOA( "Normalizer", IsGroup, IsObject, NewAttribute );
]]></Log>
<P/>
The full mechanism of <Ref Func="InParentFOA"/> is described in
chapter&nbsp;<Ref Chap="Function-Operation-Attribute Triples"/>,
however for our purposes it is sufficient to know that for such a function
the actual work is done by an operation <C>NormalizerOp</C>, an underlying 
operation for <Ref Oper="Normalizer" Label="for two groups"/> (and all the
complications are just there to be able to remember certain results) and that
the declaration of this operation is given by the first arguments, it would
be:
<Log><![CDATA[
DeclareOperation( "NormalizerOp", [IsGroup, IsObject] );
]]></Log>
<P/>
This time we decide to enter a non-default family predicate in the call to
<Ref Func="InstallMethod"/>.
We could just leave it out as in the previous call;
this would yield the default value,
the function <Ref Func="ReturnTrue"/> of arbitrary
many arguments which always returns <K>true</K>.
However, then the method might be called in some cases of inconsistent input
(for example matrix groups in different characteristics) that ought to fall
through the method selection to raise an error.
<P/>
In our situation, we want the second group to be a subgroup of the first, so
necessarily both must have the same family and we can use
<Ref Func="IsIdenticalObj"/> as family predicate.
<P/>
Now we can install the method. Again this manual is lazy and does not show
you the actual code:
<Log><![CDATA[
InstallMethod(NormalizerOp,"for nilpotent permutation groups",IsIdenticalObj,
  [IsPermGroup and IsNilpotentGroup,
   IsPermGroup and IsNilpotentGroup],
function(G,U)
  [ function body omitted ]
end);
]]></Log>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Extending the Range of Definition of an Existing Operation">
<Heading>Extending the Range of Definition of an Existing Operation</Heading>

It might be that the operation has been defined so far only for a set of
objects that is too restrictive for our purposes (or we want to install a
method that takes another number of arguments). If this is the case,
the call to <Ref Func="InstallMethod"/> causes an error message.
We can avoid this by using <Ref Func="InstallOtherMethod"/> instead.
It is also possible to re-declare an operation with another number of 
arguments and/or different filters for its arguments.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Enforcing Property Tests">
<Heading>Enforcing Property Tests</Heading>

As mentioned in Section <Ref Sect="Applicable Methods and Method Selection"/>,
&GAP; does not check unknown properties to test whether
a method might be applicable. In some cases one wants to enforce this,
however, because the gain from knowing the property outweighs the cost of
its determination.
<P/>
In this situation one has to install a method <E>without</E> the additional
property (so it can be tried even if the property is not yet known) and at high
rank (so it will be used before other methods). The first thing to do in the
actual function then is to test the property and to bail out with
<Ref Func="TryNextMethod"/> if it turns out to be <K>false</K>.
<P/>
The above <Ref Func="Exponent"/> example thus would become:
<!-- %T The above example mentioned nilpotency ... -->
<Log><![CDATA[
InstallMethod(Exponent,"test abelianity", [IsGroup],
  50,# enforced high rank
function(G)
  if not IsAbelian(G) then
    TryNextMethod();
  fi;
  [remaining function body omitted]
end);
]]></Log>
<P/>
The value <Q>50</Q> used in this example is quite arbitrary. A better way is to
use values that are given by the system inherently: We want this method
still to be ranked as high,
<E>as if it had</E> the <Ref Func="IsAbelian"/> requirement.
So we have &GAP; compute the extra rank of this:
<Log><![CDATA[
InstallMethod(Exponent,"test abelianity", [IsGroup],
  # enforced absolute rank of `IsGroup and IsAbelian' installation: Subtract
  # the rank of `IsGroup' and add the rank of `IsGroup and IsAbelian':
  SIZE_FLAGS(FLAGS_FILTER(IsGroup and IsAbelian))
  -SIZE_FLAGS(FLAGS_FILTER(IsGroup)),
function(G)
]]></Log>
the slightly complicated construction of addition and subtraction is
necessary because <Ref Func="IsGroup"/> and
<Ref Func="IsAbelian"/> might imply the <E>same</E>
elementary filters which we otherwise would count twice.
<P/>
A somehow similar situation occurs with matrix groups. Most methods for
matrix groups are only applicable if the group is known to be finite.
<P/>
However we should not enforce a finiteness test early (someone else later might
install good methods for infinite groups while the finiteness test would be
too expensive) but just before &GAP; would give a <Q>no method found</Q>
error. This is done by redispatching, see&nbsp;<Ref Sect="Redispatching"/>. For example to
enforce such a final finiteness test for normalizer calculations could be
done by:
<Log><![CDATA[
RedispatchOnCondition(NormalizerOp,IsIdenticalObj,
  [IsMatrixGroup,IsMatrixGroup],[IsFinite,IsFinite],0);
]]></Log>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Adding a new Operation">
<Heading>Adding a new Operation</Heading>

Next, we will consider how to add own operations. As an example we take the Sylow
normalizer in a group of a given prime. This operation gets two arguments,
the first has to be a group, the second a prime number.
<P/>
There is a function <Ref Func="IsPrimeInt"/>,
but no property for being prime (which
would be pointless as integers cannot store property values anyhow). So the
second argument gets specified only as positive integer:
<Log><![CDATA[
SylowNormalizer:=NewOperation("SylowNormalizer",[IsGroup,IsPosInt]);
]]></Log>
(Note that we are using <Ref Func="NewOperation"/> instead of 
<Ref Func="DeclareOperation"/> as used in the library.
The only difference other than that <Ref Func="DeclareOperation"/> saves
some typing,
is that it also protects the variables against overwriting. 
When testing code (when one probably wants to change things) 
this might be restricting. If this does not bother you, you can use
<P/>
<Log><![CDATA[
DeclareOperation("SylowNormalizer",[IsGroup,IsPosInt]);
]]></Log>
as well.)
<P/>
The filters <Ref Func="IsGroup"/> and
<Ref Func="IsPosInt"/> given are <E>only</E> used to test that
<Ref Func="InstallMethod"/> installs methods with suitable 
arguments and will be completely ignored when using
<Ref Func="InstallOtherMethod"/>. Technically one could
therefore simply use <Ref Func="IsObject"/> for all arguments
in the declaration. The
main point of using more specific filters here is to help documenting with
which arguments the function is to be used (so for example a call
<C>SylowNormalizer(5,G)</C> would be invalid).
<P/>
Of course initially there are no useful methods for newly declared
operations; you will have to write and install them yourself.
<P/>
If the operation only takes one argument and has reproducible results
without side effects, it might be worth declaring it as an attribute
instead; see Section <Ref Sect="Adding a new Attribute"/>.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Adding a new Attribute">
<Heading>Adding a new Attribute</Heading>

<Index Key="NewAttribute" Subkey="example"><C>NewAttribute</C></Index>
<Index Key="DeclareAttribute" Subkey="example"><C>DeclareAttribute</C></Index>
Now we look at an example of how to add a new attribute. As example we
consider the set of all primes that divide the size of a group.
<P/>
First we have to declare the attribute:
<P/>
<Log><![CDATA[
PrimesDividingSize:=NewAttribute("PrimesDividingSize",IsGroup);
]]></Log>
<P/>
(See&nbsp;<Ref Func="NewAttribute"/>).
This implicitly declares attribute tester and setter, it is convenient
however to assign these to variables as well:
<P/>
<Log><![CDATA[
HasPrimesDividingSize:=Tester(PrimesDividingSize);
SetPrimesDividingSize:=Setter(PrimesDividingSize);
]]></Log>
<P/>
Alternatively, there is a declaration command 
<Ref Func="DeclareAttribute"/> that executes all three
assignments simultaneously and protects the variables against overwriting:
<P/>
<Log><![CDATA[
DeclareAttribute("PrimesDividingSize",IsGroup);
]]></Log>
<P/>
Next we have to install method(s) for the attribute that compute its value.
(This is not strictly necessary. We could use the attribute also without
methods only for storing and retrieving information, but calling it for objects
for which the value is not known would produce a <Q>no method found</Q> error.)
For this purpose we can imagine the attribute simply as an one-argument
operation:
<P/>
<Log><![CDATA[
InstallMethod(PrimesDividingSize,"for finite groups",
  [IsGroup and IsFinite],
function(G)
  if Size(G)=1 then return [];
  else return Set(Factors(Size(G)));fi;
end);
]]></Log>
<P/>
<Index Key="IsAttributeStoringRep"><C>IsAttributeStoringRep</C></Index>
The function installed <E>must</E> always return a value (or call
<Ref Func="TryNextMethod"/>).
If the object is in the representation
<C>IsAttributeStoringRep</C> this return value once computed will be automatically
stored and retrieved if the attribute is called a second time. We don't have
to call setter or tester ourselves. (This storage happens by &GAP;
internally calling the attribute setter with the return value of the
function. Retrieval is by a high-ranking method which is installed under the
condition <C>HasPrimesDividingSize</C>. This method was installed automatically
when the attribute was declared.)

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Adding a new Representation">
<Heading>Adding a new Representation</Heading>

<Index Key="NewRepresentation" Subkey="example"><C>NewRepresentation</C></Index>
<Index Key="DeclareRepresentation" Subkey="example"><C>DeclareRepresentation</C></Index>
<Index Key="IsComponentObjectRep"><C>IsComponentObjectRep</C></Index>
<Index Key="IsAttributeStoringRep"><C>IsAttributeStoringRep</C></Index>
Next, we look at the implementation of a new representation of existing
objects. In most cases we want to implement this representation only for
efficiency reasons while keeping all the existing functionality.
<P/>
For example, assume we wanted (following <Cite Key="wielandt69"/>)
to implement permutation groups defined by relations.
<P/>
Next, we have to decide a few basics about the representation. All existing
permutation groups in the library are attribute storing and we probably want
to keep this for our new objects. Thus the representation must be a
subrepresentation of <C>IsComponentObjectRep and IsAttributeStoringRep</C>.
Furthermore we want each object to be a permutation group and we can imply
this directly in the representation.
<P/>
We also decide that we store the degree (the largest point that might be
moved)
in a component <C>degree</C> and the defining relations in a component
<C>relations</C> (we do not specify the format of relations here. In an actual
implementation one would have to design this as well, but it does not affect
the declarations this chapter is about).
<P/>
<Log><![CDATA[
IsPermutationGroupByRelations:=NewRepresentation(
  "IsPermutationGroupByRelations",
  IsComponentObjectRep and IsAttributeStoringRep and IsPermGroup,
  ["degree","relations"]);
]]></Log>
<P/>
(If we wanted to implement sparse matrices we might for example rather
settle for a positional object in which we store a list of the nonzero
entries.)
<P/>
We can make the new representation a subrepresentation of an existing one.
In such a case of course we have to provide all structure of this <Q>parent</Q>
representation as well.
<P/>
Next we need to check in which family our new objects will be. This will be
the same family as of every other permutation group, namely the
<C>CollectionsFamily(PermutationsFamily)</C> (where the family
<C>PermutationsFamily = FamilyObj((1,2,3))</C> has been defined already in the
library).
<P/>
Now we can write a function to create our new objects. Usually it is helpful
to look at functions from the library that are used in similar situations (for
example <Ref Oper="GroupByGenerators"/> in our case)
to make sure we have not forgotten
any further requirements in the declaration we might have to add here.
However in most cases the function is straightforward:
<P/>
<Log><![CDATA[
PermutationGroupByRelations:=function(degree,relations)
local g
  g:=Objectify(NewType(CollectionsFamily(PermutationsFamily),
		       IsPermutationGroupByRelations),
               rec(degree:=degree,relations:=relations));
end;
]]></Log>
<P/>
It also is a good idea to install a <Ref Func="PrintObj"/>
and possibly also a <Ref Func="ViewObj"/> method
&ndash;otherwise testing becomes quite hard:
<P/>
<Log><![CDATA[
InstallMethod(PrintObj,"for perm grps. given by relations",
  [IsPermutationGroupByRelations],
function(G)
  Print("PermutationGroupByRelations(", G!.degree,",",G!.relations,")");
end);
]]></Log>
<P/>
Next we have to write enough methods for the new representation so that the
existing algorithms can be used. In particular we will have to implement
methods for all operations for which library or kernel provides methods for
the existing (alternative) representations. In our particular case there are
no such methods. (If we would have implemented sparse matrices we
would have had to implement methods for the list access and assignment
functions, see <Ref Sect="Basic Operations for Lists"/>.)
However the existing way permutation groups are represented is by
generators. To be able to use the existing machinery we want to be able to
obtain a generating set also for groups in our new representation. This can
be done (albeit not very effectively) by a stabilizer calculation in the
symmetric group given by the <C>degree</C> component. The operation function to
use is probably a bit complicated and will depend on the format of the
<C>relations</C> (we have not specified in this example). In the following
method we use <C>operationfunction</C> as a placeholder;
<P/>
<Log><![CDATA[
InstallMethod(GeneratorsOfGroup,"for perm grps. given by relations",
  [IsPermutationGroupByRelations],
function(G)
local S,U;
  S:=SymmetricGroup(G!.degree);
  U:=Stabilizer(S,G!.relations,  operationfunction );
  return GeneratorsOfGroup(U);
end);
]]></Log>
<P/>
This is all we <E>must</E> do. Of course for performance reasons one might want
to install methods for further operations as well.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Components versus Attributes">
<Heading>Components versus Attributes</Heading>

In the last section we introduced two new components, <C>G!.degree</C> and
<C>G!.relations</C>. Technically, we could have used attributes instead.
There is no clear distinction which variant is to be preferred: An attribute
expresses part of the functionality available to certain objects (and thus
could be computed later and probably even for a wider class of objects), a
component is just part of the internal definition of an object.
<P/>
So if the data is <Q>of general interest</Q>, if we want the user to have
access to it, attributes are preferable. Moreover, attributes can be used 
by the method selection (by specifying the filter <C>HasAttr</C> for an 
attribute <C>Attr</C>). They provide a clean 
interface and their immutability makes it safe to hand the data to a user who potentially
could corrupt a components entries.
<P/>
On the other hand more <Q>technical</Q> data (say the encoding of a sparse
matrix) is better hidden from the user in a component, as declaring it as an
attribute would not give any advantage.
<P/>
Resource-wise, attributes need more memory (the attribute setter and
tester are implicitly declared, and one filter bit is required), the
attribute access is one further function call in the kernel, thus components
might be an immeasurable bit faster.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Adding new Concepts">
<Heading>Adding new Concepts</Heading>

Now we look how to implement a new concept for existing objects and fit
this in the method selection. Three examples that will be made more explicit
below would be groups for which a <Q>length</Q> of elements (as a word in
certain generators) is defined, groups that can be decomposed as a
semidirect product and M-groups.
<P/>
In each case we have two possibilities for the declaration. We can
either declare it
as a property or as a category. Both are eventually filter(s) and in this way
indistinguishable for the method selection. However, the value of
a property for a particular object can be unknown at first and later
in the session be computed (to be <K>true</K> or <K>false</K>).
This is implemented by reserving two filters for each property, one
indicating whether the property value is known, and one, provided
the value is known, to indicate the actual boolean value.
Contrary to this, the decision whether or not an object lies in a
category is taken at creation time and this is implemented using
a single filter.
<P/>
<List>
<Mark>Property:</Mark>
<Item>
Properties also are attributes:
If a property value is not known for an object, &GAP; tries to find a
method to compute the property value. If no suitable method is found, an
error is raised.
</Item>
<Mark>Category:</Mark>
<Item>
An object is in a category if it has been created in it. Testing the
category for an object simply returns this value. Existing objects cannot
enter a new category later in life. This means that in most cases one has to
write own code to create objects in a new category.
<P/>
If we want to implement a completely new concept so that new
operations are defined only for the new objects &ndash;for example bialgebras
for which a second scalar multiplication is defined&ndash;
usually a category is chosen.
<P/>
Technically, the behaviour of the category <C>IsXYZ</C>, declared as subcategory
of <C>IsABC</C> is therefore exactly the same as if we would declare <C>IsXYZ</C> to
be a property for <C>IsABC</C> and install the following method:
<Log><![CDATA[
InstallMethod(IsXYZ,"return false if not known",[IsABC],ReturnFalse);
]]></Log>
<P/>
(The word <C>category</C> also has a
well-defined mathematical meaning, but this does not need to concern us at
this point.
The set of objects which is defined to be a (&GAP;) category does
not need to be a category in the mathematical sense, vice versa not every
mathematical category is declared as a (&GAP;) category.)
</Item>
</List>
Eventually the choice between category and property often  becomes a matter of
taste or style.
<P/>
Sometimes there is even a third possibility (if you have &GAP;&nbsp;3 experience
this might reflect most closely <Q>an object whose operations record is
<C>XYOps</C></Q>): We might want to indicate this new concept simply by the fact
that certain attributes are set. In this case we could simply use the
respective attribute tester(s).
<P/>
The examples given below each give a short argument why the
respective solution was chosen, but one could argue as well for other
choices.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="Example: M-groups">
<Heading>Example: M-groups</Heading>

<!-- %T add a sentence that the library contains this already; -->
<!-- %T the name of the library function is <C>IsMonomialGroup</C> -->

M-groups are finite groups for which all irreducible complex
representations are induced from linear representations of subgroups, it
turns out that they are all solvable and that every supersolvable group is
an M-group. See <Cite Key="Isa76"/> for further details.
<P/>
Solvability and supersolvability both are testable properties. We therefore
declare <C>IsMGroup</C> as a property for solvable groups:
<Log><![CDATA[
IsMGroup:=NewProperty("IsMGroup",IsSolvableGroup);
]]></Log>
The filter <Ref Func="IsSolvableGroup"/> in this declaration
<E>only</E> means that methods
for <C>IsMGroup</C> by default can only be installed for groups that are (and
know to be) solvable (though they could be installed for more general
situations using <Ref Func="InstallOtherMethod"/>).
It does not yet imply that M-groups
are solvable. We must do this deliberately via an implication and we use the
same technique to imply that every supersolvable group is an M-group.
<Log><![CDATA[
InstallTrueMethod(IsSolvableGroup,IsMGroup);
InstallTrueMethod(IsMGroup,IsSupersolvableGroup);
]]></Log>
<!-- %T The library is more accurate: -->
<!-- %T Monomiality is defined only for <E>finite</E> groups, -->
<!-- %T whereas infinite groups might be supersolvable! -->
<P/>
Now we might install a method that tests for solvable groups whether they
are M-groups:
<Log><![CDATA[
InstallMethod(IsMGroup,"for solvable groups",[IsSolvableGroup],
function(G)
  [... code omitted. The function must return `true' or `false' ...]
end);
]]></Log>
Note that this example of declaring the <C>IsMGroup</C> property for 
solvable groups is not a part of the &GAP; library, which uses a 
similar but different filter <Ref Prop="IsMonomialGroup"/>.
</Subsection>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="Example: Groups with a word length">
<Heading>Example: Groups with a word length</Heading>

Our second example is that of groups for whose elements a <E>word length</E>
is defined. (We assume that the word length is only defined in the context
of the group with respect to a preselected generating set
but not for single elements alone. However we will not delve into any
details of how this length is defined and how it could be computed.)
<P/>
Having a word length is a feature which enables other operations (for
example a <Q>word length</Q> function). This is exactly what categories are
intended for and therefore we use one.
<P/>
First, we declare the category. All objects in this category are groups and
so we inherit the supercategory <Ref Func="IsGroup"/>:
<P/>
<Log><![CDATA[
DeclareCategory("IsGroupWithWordLength",IsGroup);
]]></Log>
<P/>
We also define the operation which is <Q>enabled</Q> by this category, the word
length of a group element, which is defined for a group and an element
(remember that group elements are described by the category 
<Ref Func="IsMultiplicativeElementWithInverse"/>):
<P/>
<Log><![CDATA[
DeclareOperation("WordLengthOfElement",[IsGroupWithWordLength,
  IsMultiplicativeElementWithInverse]);
]]></Log>
<P/>
We then would proceed by installing methods to compute the word length in
concrete cases and might for example add further operations to get shortest
words in cosets.

</Subsection>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="Example: Groups with a decomposition as semidirect product">
<Heading>Example: Groups with a decomposition as semidirect product</Heading>
<P/>
<Index Key="DeclareAttribute!example"><C>DeclareAttribute!example</C></Index>
The third example is groups which have a (nontrivial) decomposition as a
semidirect product. If this information has been found out, we want to be
able to use it in algorithms. (Thus we do not only need the fact <E>that</E>
there is a decomposition, but also the decomposition itself.)
<P/>
We also want this to be applicable to every group and not only for groups
which have been explicitly constructed via
<Ref Func="SemidirectProduct" Label="for acting group, action, and a group"/>.
<P/>
Instead we simply declare an attribute
<C>SemidirectProductDecomposition</C> for groups.
(Again, in this manual we don't go in the details of how such an
decomposition would look like).
<P/>
<Log><![CDATA[
DeclareAttribute("SemidirectProductDecomposition",IsGroup);
]]></Log>
<P/>
If a decomposition has been found, it can be stored in a group using
<C>SetSemidirectProductDecomposition</C>. (At the moment all groups in &GAP; are
attribute storing.)
<P/>
Methods that rely on the existence of such a decomposition then get
installed for the tester filter <C>HasSemidirectProductDecomposition</C>.
<!-- %T but this filter expresses the <E>knowledge</E> of a decomposition, -->
<!-- %T not the <E>existence</E>!! -->

</Subsection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Creating Own Arithmetic Objects">
<Heading>Creating Own Arithmetic Objects</Heading>

Finally let's look at a way to create new objects with a user-defined
arithmetic such that one can form for example groups, rings or vector spaces
of these elements. This topic is discussed in much more detail in
chapter&nbsp;<Ref Chap="An Example -- Designing Arithmetic Operations"/>, in this section we
present a simple approach that may be useful to get started but does not
permit you to exploit all potential features.
<P/>
The basic design is that the user designs some way to represent her objects
in terms of &GAP;s built-in types, for example as a list or a record. 
We call this the <Q>defining data</Q> of the new objects.
Also provided are functions that perform arithmetic on this <Q>defining
data</Q>, that is they take objects of this form and return objects that
represent the result of the operation. The function
<Ref Func="ArithmeticElementCreator"/> then is called to provide a wrapping
such that
proper new &GAP;-objects are created which can be multiplied etc. with the
default infix operations such as <C>*</C>.
<P/>
<#Include Label="ArithmeticElementCreator">

<Subsection Label="expl:ArithmeticElementCreator">
<Heading>Example: ArithmeticElementCreator</Heading>

As the first example we look at subsets of <M>\{ 1, \ldots, 4 \}</M> and define an
<Q>addition</Q> as union and <Q>multiplication</Q> as intersection.
These operations are both commutative and we want the resulting elements to
know this.
<P/>
We therefore use the following specification:
<P/>
<Example><![CDATA[
gap> # the whole set
gap> w := [1,2,3,4];
[ 1, 2, 3, 4 ]
gap> PosetElementSpec :=rec(
>   # name of the new elements
>   ElementName := "PosetOn4",
>   # arithmetic operations
>   One := a -> w,
>   Zero := a -> [],
>   Multiplication := function(a, b) return Intersection(a, b); end,
>   Addition := function(a, b) return Union(a, b); end,
>   # Mathematical properties of the elements
>   MathInfo := IsCommutativeElement and
>               IsAssociativeElement and
>               IsAdditivelyCommutativeElement
> );;
gap> mkposet := ArithmeticElementCreator(PosetElementSpec);
function( x ) ... end
]]></Example>
<P/>
Now we can create new elements, perform arithmetic on them and form domains:
<P/>
<Example><![CDATA[
gap> a := mkposet([1,2,3]);
[ 1, 2, 3 ]
gap> CategoriesOfObject(a);
[ "IsExtAElement", "IsNearAdditiveElement", 
  "IsNearAdditiveElementWithZero", "IsAdditiveElement", 
  "IsExtLElement", "IsExtRElement", "IsMultiplicativeElement", 
  "IsMultiplicativeElementWithOne", "IsAssociativeElement",
  "IsAdditivelyCommutativeElement", "IsCommutativeElement",
  "IsPosetOn4" ]
gap> a=[1,2,3];
false
gap> UnderlyingElement(a)=[1,2,3];
true
gap> b:=mkposet([2,3,4]);
[ 2, 3, 4 ]
gap> a+b;
[ 1, 2, 3, 4 ]
gap> a*b;
[ 2, 3 ]
gap> s:=Semigroup(a,b);
<semigroup with 2 generators>
gap> Size(s);
3
]]></Example>
<P/>
The categories <C>IsPosetOn4</C> and <C>IsPosetOn4Collection</C> can be used to
install methods specific to the new objects.
<Example><![CDATA[
gap> IsPosetOn4Collection(s);
true
]]></Example>

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


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