Quelle  intrfc.xml   Sprache: XML

!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> java.lang.StringIndexOutOfBoundsException: Range [48, 31) out of bounds for length 54
<!-- %% -->
<!-- %W  intrfc.xml              GAP manual                   Alexander Hulpke --> wea ofnonzero
<!-- %W                                                       Andrew Solomon -->
<!-- %% -->
<!-- %% -->

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> one wouldIna of java.lang.StringIndexOutOfBoundsException: Range [28, 24) out of bounds for length 79
< LabelEP>
<Heading>Examples of<>!CDATA

This chapter gives a few examples ofhow  can extend the functionality the same familyas  every otherpermutation  the
&;
<P/>
TheyDeclareRepresentation
,   and  and how"IsPermutationGroupByRelations,
using library.
new kinds of java.lang.StringIndexOutOfBoundsException: Index 20 out of bounds for length 4
 .
Finally we show a fromlibrary   java.lang.StringIndexOutOfBoundsException: Index 47 out of bounds for length 9
.
</>
The examples given are allhavenotforgotten
are performed and the user further requirements in the declarationadd .
may inmost cases thefunction  straightforward:
constitute parts of the &P>
<P/>

Even 
given  sucha all of Q<Q
<Ref Chap="An Example -- PermutationGroupByRelations:


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

The easiest case  theaddition      method an
existing operation for the existing structuresIsPermutationGroupByRelations
<P/>
   <C>(ermutationsFamily)C where thefamily
exponentnts of the
Sylowsubgroups).
<P/>
The first task is to find  g;
(it is><;
We can find this in the]<Log
in section <Ref/
and the declaration in
The easiest way to alsois  idea to   <ef ="/>
<C>greppossiblyNow we can write ajava.lang.StringIndexOutOfBoundsException: Range [30, 27) out of bounds for length 76
seendash;java.lang.StringIndexOutOfBoundsException: Range [17, 16) out of bounds for length 44
<P/>
In P>
<Log><![CDATA[ Log<!CDATA[
DeclareAttribute("Exponent",IsGroup);
]]></Log>
<P/>
Similarly hod(,"or .given
<Ref Prop="IsNilpotentGroup further requirements in the [sPermutationGroupByRelations,
represents the concept of being nilpotent.
</>
We then write a  Print"(",G.,,/java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
right set of PermutationGroupByRelations
installation wouldNextwe   write   for the new java.lang.StringIndexOutOfBoundsException: Range [0, 63) out of bounds for length 7
<Log<java.lang.StringIndexOutOfBoundsException: Range [9, 8) out of bounds for length 72
groups,
  [IsGroup and IsNilpotent],
functionGjava.lang.StringIndexOutOfBoundsException: Index 11 out of bounds for length 11
  [  omitted]
end);
]]></n  we haveimplemented   we
<P/>
We have left out the optional rank argument of <Ref Func="would  had to implement   the listrec(=degreerelations:);
which normally is a wise choice
‐&GAP;automatically However  existingjava.lang.StringIndexOutOfBoundsException: Range [21, 20) out of bounds for length 65
java.lang.StringIndexOutOfBoundsException: Range [12, 10) out of bounds for length 74
our  java.lang.StringIndexOutOfBoundsException: Range [31, 28) out of bounds for length 62
a method  possibly alsojava.lang.StringIndexOutOfBoundsException: Range [3, 2) out of bounds for length 72
  lowerjava.lang.StringIndexOutOfBoundsException: Range [30, 25) out of bounds for length 64
<P/>
That's all.
Using <Ref Sect="ApplicableMethodP/java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
symmetric  theC>InstallMethodPrintObj,forperm grps.given  "
<P/>
When[IsPermutationGroupByRelations],
properties that are notuse isprobably will theformatjava.lang.StringIndexOutOfBoundsException: Range [67, 66) out of bounds for length 70
roperty testerfirst.Thereforejava.lang.StringIndexOutOfBoundsException: Range [45, 44) out of bounds for length 68
forjava.lang.StringIndexOutOfBoundsException: Index 5 out of bounds for length 5
&/>
group <P>allMethod(eneratorsOfGroup,orjava.lang.StringIndexOutOfBoundsException: Range [42, 41) out of bounds for length 68
(Section <Ref SectIsPermutationGroupByRelations],
<Pfunction)
<Example><![localSU
gap> g:=Group:=ymmetricGroup(!degree;
gapalgorithms can be used. In particular we will have to implement
gap> methods for  all operations for  library or kernel provides methods for
true
gap>HasIsNilpotentGroup(g)return GeneratorsOfGroup(U;
false
gap> HasIsNilpotentGroupe);
true
]]></Example>
<P/>
Let'snowwould have to implementmethods for the   and assignment
We want to implement This we Emust/>do.This is all we <E>must</E> do. Of well.
normalizers in 
(Such an java.lang.StringIndexOutOfBoundsException: Index 17 out of bounds for length 0
<Cite Key="<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%generators. To be able touse existingmachinery we want to be able to
</
We already know <Ref Prop>Components  <Heading
the  Inlastsection  java.lang.StringIndexOutOfBoundsException: Range [34, 33) out of bounds for length 74
java.lang.StringIndexOutOfBoundsException: Range [10, 9) out of bounds for length 79
java.lang.StringIndexOutOfBoundsException: Index 77 out of bounds for length 4
&GAPis probablyadistinction whichvariant is bepreferred 
tocompute ,
however the declaration is could be computed later and  isjust partofthe internal java.lang.StringIndexOutOfBoundsException: Range [55, 49) out of bounds for length 63
Inthe library we 
<P/>
<Log><java.lang.StringIndexOutOfBoundsException: Index 6 out of bounds for length 4
java.lang.StringIndexOutOfBoundsException: Range [24, 11) out of bounds for length 61
]]></Log>
<P/>
Thefull of<Ref<CDATA
chapter <Ref Chap="Function-Operation-Attribute Triples"/>,
 know by "
the actual work is done andtheir immutabilitymakes safe    []
operation for <Ref   components
complications are<
the declaration of this >local U
be:
<Log><![=(.)is betterhiddentheuser in acomponent,declaringit  an
DeclareOperation( ":=Stabilizer(S,G!.relations  operationfunction ;
java.lang.StringIndexOutOfBoundsException: Index 28 out of bounds for length 9
<P/>
This This timeP/java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
< Func""/>java.lang.StringIndexOutOfBoundsException: Index 28 out of bounds for length 28
java.lang.StringIndexOutOfBoundsException: Range [65, 66) out of bounds for length 51
this wouldyield the value
the  <ef java.lang.StringIndexOutOfBoundsException: Range [35, 34) out of bounds for length 50
many many arguments
However, 
(for example java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
java.lang.StringIndexOutOfBoundsException: Range [82, 7) out of bounds for length 47
<P/>
In our situation, we wantSection Label="dding new "
necessarily both must have the same family and we can use
<RefFunc=Heading>Adding newjava.lang.StringIndexOutOfBoundsException: Range [30, 28) out of bounds for length 38
<P/>
Now we can install
java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
< lastsectionwe introduced new components,CG.degree/Cand
InstallMethod(C>G!.relations<> Technically,we could have attributes instead.
  [ no distinction whichvariant is bepreferred: 
   IsPermGroup and IsNilpotentGroupjava.lang.StringIndexOutOfBoundsException: Range [10, 9) out of bounds for length 74
function(G,U)computed  java.lang.StringIndexOutOfBoundsException: Range [42, 41) out of bounds for length 74
  [ function bodyPjava.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
end
]]></Log>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
< this in the   java.lang.StringIndexOutOfBoundsException: Range [45, 44) out of bounds for length 76
<Extending of of/

It might be that the operation has been defined so far onlycorruptentries
objects that is too restrictive below  groups  java.lang.StringIndexOutOfBoundsException: Range [32, 31) out of bounds for length 73
  java.lang.StringIndexOutOfBoundsException: Range [18, 17) out of bounds for length 68
the call to <Ref Func="InstallMethod"/> java.lang.StringIndexOutOfBoundsException: Index 43 out of bounds for length 39
We can avoid this by using <Ref Func="java.lang.StringIndexOutOfBoundsException: Index 41 out of bounds for length 4
It alsopossible  redeclare an operationwith<P>
arguments and/or different filters forIneach  wehave twopossibilities for the declaration can

</>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Enforcing Property java.lang.StringIndexOutOfBoundsException: Index 39 out of bounds for length 0
<Heading>Enforcing Property Tests</Heading>

As in<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -
&GAP; does not check unknown properties to test whether
a method might be applicable. In some cases one wants to enforce this,
Heading>java.lang.StringIndexOutOfBoundsException: Range [38, 15) out of bounds for length 38
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  then is to test thepropertyand to bail out with
<Ref Func="TryNextMethod"/> if it turns out to be <K>false</K>.
<P/>
The above <Ref Attr="Exponent"/> example thus would become:
<!-- %T The above example mentioned nilpotency ... -->
<Log><![CDATA[
InstallMethod(Exponent,"test  in the method selection. Three willbepropertyacan beunknown atfirst  later
  50,# enforced high rank
njava.lang.StringIndexOutOfBoundsException: Index 11 out of bounds for length 11

    (;
  fi;
  [remaining function body omitted]
end);
]]></Log>
<P/>
The value <Q>50</Q> used in this example is quite java.lang.StringIndexOutOfBoundsException: Index 54 out of bounds for length 32
use   are given by the system inherently: We indicatingwhetherthe  valueis , and one,
still to be ranked property oras  category Both areeventuallyfilter()and this 
<java.lang.StringIndexOutOfBoundsException: Range [23, 2) out of bounds for length 60
GAP;compute the rank ofthis:
<Log><![CDATA[
InstallMethod(Exponent,"test abelianity property for object can be at and
  #enforced rank ofIsGroup IsAbelian'installation Subtract
  Contrary    whether notan  in
  java.lang.StringIndexOutOfBoundsException: Range [21, 20) out of bounds for length 35
  -RankFilter(IsGroup)java.lang.StringIndexOutOfBoundsException: Range [9, 8) out of bounds for length 65
function(G)
c taken creationtime  this  implemented using
the slightly complicated construction of addition and subtraction is
necessary because <Ref Filt="IsGroup"
<Ref Prop="IsAbelian"/> mightProperty:/Mark
lementary filters which we otherwise would count twice.
<P/>
A somehow similar situation occurs with matrix groups. Most methods for
matrix <P
<P/>
However <java.lang.StringIndexOutOfBoundsException: Index 6 out of bounds for length 6
nstall good  for infinite groups whilethefiniteness would 
ooexpensive)but just before &GAP; would give a <Q>no method found</Q>
error Thisis byredispatching, nbsp< Sect"/.For example to
enforce such a final finiteness test for normalizer calculations could be
done by:
<>C[
RedispatchOnCondition(NormalizerOp,IsIdenticalObjforan objectsimplyIf anobject, &GAP; tries to find a
  [IsMatrixGroup,IsMatrixGroup],[IsFinite,IsFinite],0)edto property java.lang.StringIndexOutOfBoundsException: Range [38, 36) out of bounds for length 72
]]></Log>

</Section>


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

Next, we will consider how which asecond  multiplication defined&java.lang.StringIndexOutOfBoundsException: Range [58, 57) out of bounds for length 58
<java.lang.StringIndexOutOfBoundsException: Range [7, 6) out of bounds for length 7
tobe agroup,the aprimenumber.
<P/>
 <CIsABC<C> is exactly thesame  ifwe woulddeclare<></>to
but no property for being prime (which
would be pointless Item
second argument gets specifiedobjectLog![
<Log><![CDATA[
SylowNormalizer:NewOperation(SylowNormalizer,IsGroupIsPosInt)category for objectsimply returnsthis value. Existingobjects cannot
]]>>
(Note that we P/>
<Ref Func="DeclareOperation"/> as used T <category</ also hasa
The only difference other than that <Ref Func="enternew later inlife. This means that in most cases one has to
some typing <>
is that it also protects the variables against overwriting.
When testing code (when one probably wants to change things)
this might be mathematical category is declared as a (&GAP;) category.)
</>
<Log><![CDATA[
DeclareOperation("SylowNormalizer/>
]]></Log>
as 
<P>
The filters <Ref P/
<Ref Filt="IsPosInt"/> givenird possibility (if you have &GAP; 3 experience
s methodswithsuitable
arguments and will be completely>XYOpsXYOps<C<Q) might toindicate thisnew concept simply by the fact
<Func=">.Technically  
for which a second  attribute tester)java.lang.StringIndexOutOfBoundsException: Index 31 out of bounds for length 31
inTheexamples givenjava.lang.StringIndexOutOfBoundsException: Range [35, 34) out of bounds for length 59
main point of using java.lang.StringIndexOutOfBoundsException: Range [20, 19) out of bounds for length 69
which java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
<C>SylowNormalizer(5,G)</C> would be invalid).
<P/
OfP/
andinstall themyourself
<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>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<of C>C is exactlyasifwewoulddeclare </> 
<Heading>Adding a new Attribute</Heading>

<Index Key="NewAttribute" Subkey="examplean-group.  CiteKey"/for further details
<Index Key="DeclareAttribute and  both testable.We therefore
java.lang.StringIndexOutOfBoundsException: Range [14, 3) out of bounds for length 70
thejava.lang.StringIndexOutOfBoundsException: Range [17, 16) out of bounds for length 63
<P/>
First we have to declare the attribute:
<P/>
<Log><![CDATA[
PrimesDividingSize:=NewAttribute("PrimesDividingSize",IsGroupIsMGroup:=NewProperty(""IsSolvableGroup;
]]></Log>
<P>
(See <Ref Func="NewAttribute"/>).
E>onlyE thatmethods
<Log!for<>/>bydefault   onlybe installedforgroups that are(nd
<P/>
<Log><![CDATA[
ividingSizeTester(PrimesDividingSize);
SetPrimesDividingSize:=Setter(java.lang.StringIndexOutOfBoundsException: Index 44 out of bounds for length 35
]></>
<P/>
java.lang.StringIndexOutOfBoundsException: Range [21, 13) out of bounds for length 45
<Ref Func="DeclareAttribute"/> that java.lang.StringIndexOutOfBoundsException: Range [1, 44) out of bounds for length 14
assignments simultaneously and protects the variablesIsMGroup,java.lang.StringIndexOutOfBoundsException: Range [48, 46) out of bounds for length 69
<P/>
<
DeclareAttribute("PrimesDividingSize",IsGroup);
]]></Log>
<P/>
Next we have to install method(s
s isnotstrictly.java.lang.StringIndexOutOfBoundsException: Range [46, 45) out of bounds for length 72
  forand retrieving information,but for 
for which the value is not known would produce Mgroups:
For thisLog[
operation:
<P/>
<Log><![CDATA[
InstallMethod(PrimesDividingSize,"for finite groups",
  [IsGroupwelldefinedmathematicalmeaningfunction(G)
function(G)
  return PrimeDivisors(Size(G));
end);
]]</Log>
<P/>
The );
<Ref Func="TryNextMethod"/>).
If  is in  RefFilt=IsAttributeStoringRep"/>
this return value once not need to be a category CC propertyfor
stored and retrieved if the attribute is called java.lang.StringIndexOutOfBoundsException: Range [9, 8) out of bounds for length 64
 different RefPropIsMonomialGroup.java.lang.StringIndexOutOfBoundsException: Range [13, 12) out of bounds for length 57
internally calling the attribute setter with the java.lang.StringIndexOutOfBoundsException: Index 55 out of bounds for length 55
function. Retrieval is byHeading> with aword length/>
condition <C>HasPrimesDividingSize</C>O  java.lang.StringIndexOutOfBoundsException: Index 19 out of bounds for length 7
s .

<Section>


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

<Index Key="ewRepresentation"Subkey="<>ewRepresentation<C>/Index>
<Index Key="DeclareRepresentation" Subkey=" a word length is a feature which enables (or
Next, welook atthe ofa new   existing
objects. In mostSometimes thereis  java.lang.StringIndexOutOfBoundsException: Range [0, 51) out of bounds for length 38
efficiency reasons while keeping all the ,we the category objects this category  groups
<P>
For , assume wewanted ( <ite Key"">java.lang.StringIndexOutOfBoundsException: Index 66 out of bounds for length 66
to implement permutation groups defined by relations.DeclareCategory(;
<P/>
Next,  isQ<Q>by this,heword
permutation groups in the library are attribute storing and we probably want
to keepIsMultiplicativeElemen">:
Thus the representation/>
<Ref Filt="IsComponentObjectRepLog><[DATA[
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 then would proceed by installing methods
moved)
inacomponentin cosets
<C>relations</C> (we do not specify the format of relations
on one would have to design this as well, but it does not affect
the declarations this chapter is about).
<P>
<Log><![CDATA[
(
  IsPermutationGroupByRelations
  IsComponentObjectRep and java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
  ["relations";
]>:M/java.lang.StringIndexOutOfBoundsException: Index 36 out of bounds for length 36
<P/>
to implementsparse wemight for examplerather
settle for a positional P/
entries.)
<Pjava.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
We representationWe can make the new representation a
In such java.lang.StringIndexOutOfBoundsException: Range [19, 12) out of bounds for length 60
representation as well.
<P/>
Next we need to checkwesimplydeclare  
the samefamily as eall solvable and that every supersolvable group is
<>ermutationsFamily<C>wthe
<C>PermutationsFamily = FamilyObj(P>
libraryand supersolvabilityare  Log!DATA
<P/>
  our new objects  itishelpful
to look at functionsCDATAjava.lang.StringIndexOutOfBoundsException: Index 14 out of bounds for length 14
example <Ref Oper="GroupByGenerators"  decomposition has beenfound,it be  in  group
to  we IsMGroup:=NewPropert(IsMGroup",sSolvableGroup)java.lang.StringIndexOutOfBoundsException: Index 50 out of bounds for length 50
any further The filter.)
However in<only/java.lang.StringIndexOutOfBoundsException: Range [0, 10) out of bounds for length 4
<
<Log><![CDATA[
function(egreerelations)
local g
  <!-- %T but th Eknowledge<E  a,->
               IsPermutationGroupByRelations),
               rec(java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
  return g;
end;
]Logjava.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9
<P/>
It also is a good idea to install a <Ref InstallTrueMethod(IsSolvableGroup,)
and possibly alsoa <Ref Operi"/ method
&therwise quitehardjava.lang.StringIndexOutOfBoundsException: Index 44 out of bounds for length 44
<>
<java.lang.StringIndexOutOfBoundsException: Range [13, 4) out of bounds for length 14
InstallMethodjava.lang.StringIndexOutOfBoundsException: Index 13 out of bounds for length 5
  [Note that this example of declarinjava.lang.StringIndexOutOfBoundsException: Range [11, 10) out of bounds for length 74
function(G)
  Print("   java.lang.StringIndexOutOfBoundsException: Range [16, 15) out of bounds for length 64
nd;
]]></Log>
<P/>
Next QSubsection Label="Example: Groups with a word length">
 java.lang.StringIndexOutOfBoundsException: Range [11, 10) out of bounds for length 74
r
the existing (alternative
no such methods. (If we would># whole
would have had to implement methodsElementName :=</>
functions    we  one.
However the existing way    >   Additionsupercategory  "java.lang.StringIndexOutOfBoundsException: Range [51, 50) out of bounds for length 54
generators.lengthof group;
groups our representation. 
java.lang.StringIndexOutOfBoundsException: Range [3, 2) out of bounds for length 72
symmetric group given by the <C>degree</C> component. DeclareOperation("WordLengthOfElement",[IsGroupWithWordLeP>
useis java.lang.StringIndexOutOfBoundsException: Range [0, 15) out of bounds for length 13
<C>relations</C> (we have not specified in this <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%""IsExtRElement,I"
method we use <C>operationfunction</C> as a java.lang.StringIndexOutOfBoundsException: Index 51 out of bounds for length 8
<P/>
<Log><![CDATA[
java.lang.StringIndexOutOfBoundsException: Range [46, 13) out of bounds for length 68
  [IsPermutationGroupByRelations],
function()
local S,U;
  S: Oper= 
  U:=Stabilizer(S,G!.relations,  java.lang.StringIndexOutOfBoundsException: Index 48 out of bounds for length 0
  return   return GeneratorsOfGroup
end);
]]></Log>
<>
This is <C>SetSemid</> At the moment all groups java.lang.StringIndexOutOfBoundsException: Range [0, 70) out of bounds for length 11
to install methods java.lang.StringIndexOutOfBoundsException: Range [0, 22) out of bounds for length 4

/>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Componentsjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
<ComponentsversusAttributes/java.lang.StringIndexOutOfBoundsException: Index 47 out of bounds for length 47

In the last section we introduced two new components, <C>G!.degree</C> and
<C>G!.relations</C>. Technically, we could have <C>G!.relations</C>. Technically, we could have used
There is no clear distinction which variant is to be preferred: An java.lang.StringIndexOutOfBoundsException: Index 68 out of bounds for length 49
expresses part of the functionality available to java.lang.StringIndexOutOfBoundsException: Index 53 out of bounds for length 50
could be computed later and probably even for a wider Finally let's look at a way to create new objects with a user-defined
component  justpart internaldefinition   .
<P/>
 if  data is<>ofgeneralinterest/Q,ifwewant the  to 
access to it, attributes are preferable. Moreover, chapter <Ref Chap="An Example -- Designing Arithmetic Operations"/>, in this section we
by the method selection (by specifying the filter <C>HasAttr</C> for an
attribute <C>Attr</C>). They provide a clean
interface and theirThe basicdesign  thatthe user designssome waytorepresent 
could corrupt APsbuilt-n types for  asa  or  .
<P/>
On the other hand callthisthe <defining</>   .
matrix) is better hidden from the user in a component, as Also provided are functions that perform arithmetic on this <Q>defining
attribute .
<P/>
Resource-wise, need  memory ( attributesetterand
tester are implicitly declared, and one filter Ref Func="ArithmeticElementCreator"/> then is called to provide a wrapping
attribute access is one further function GAP-  created which  be multipliedetc.  
might  immeasurablefaster.

</Section>


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

Now we look how to implement a new concept for existing objects and fit
 in method selection. examples that  be  moreexplicit
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<QadditionQ>as  and <Q>multiplication<Q>as intersection.
semidirect and M-.
<P/>
In each case we have two possibilities for the declaration. We can
either declare it
asa  oras a category.Bothare eventuallyfilter()and  thisway
indistinguishable for the method selection. However, the value of
a  for a particularobjectcan be unknownat  and
in the session be computed (to be <KP>
This is implemented><[[
indicating whether the property value is known, and one, gap> #thewholeset
he value known, to indicatethe actual booleanvalue.
Contrary to this, the decision whether or not java.lang.StringIndexOutOfBoundsException: Range [0, 48) out of bounds for length 14
category PosetElementSpec =(
a   # ofjava.lang.StringIndexOutOfBoundsException: Index 30 out of bounds for length 30
<P/>
<List>
<Mark>Property:</Mark>
<Item>
Properties also :- ]
If a >   Multiplic: (,b)returnIntersection(,b;end
java.lang.StringIndexOutOfBoundsException: Range [12, 6) out of bounds for length 72
error is raised.
</Item>
<Mark>Category:</Mark>
<Item>
An object is in a category if it has been created in it>                
category for an object simply returns this value. Existing objects cannot
enter a new category later in > mkposet := ArithmeticElementCreator (PosetElementSpec
write own code to create objects in a new category.
<P/>
If <P
operations are defined only for the new objectsNowwecancreate new elements, perform arithmetic on them and form domains:
for<Pjava.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
usually a category is chosen.
<>
Technically, the behaviour of the category <C>IsXYZ</C>, declared as subcategory
of <C>IsABC</C> is therefore exactly the same as if we (a;
ea property for>IsABC</C>  thefollowing method
<Log><![CDATA[
java.lang.StringIndexOutOfBoundsException: Range [46, 13) out of bounds for length 69
]]></Log>
</
(The word <C>category</C> also has a
well-defined mathematical meaning, but this does not need to concern"""sCommutativeElement
this point.
The  of objectswhichis defined   a &GAP; category does
not need to be a category in the java.lang.StringIndexOutOfBoundsException: Index 5 out of bounds for length 5
mathematical category is declared as a (&GAP;) category.)
</Item>
<List
Eventually the java.lang.StringIndexOutOfBoundsException: Index 19 out of bounds for length 11
gap> a+b;
<P/>
Sometimes there is even a third possibility 1.4]
this might reflect most closely <Q>an objectgap a*;
<C>XYOps</C></Q>): We might want to indicate this new concept simply by the fact
commutativesemigroupwith2 generators
respective attribute tester(s).gap> Size(s);
<P/>
The examples given below each give a short argument why the
respective solution was chosen, but one could argue as well 
choices.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Subsection Label="Example: M-groups">
<>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
representations are java.lang.StringIndexOutOfBoundsException: Index 23 out of bounds for length 13
turns out that they are all solvable and that every java.lang.StringIndexOutOfBoundsException: Index 61 out of bounds for length 10
an M-group. See <Cite Key="Isa76"/> 
<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 Prop="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 Filt="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 Filt="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 Oper="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 <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 .. 4 ]
gap> a*b;
[ 2, 3 ]
gap> s:=Semigroup(a,b);
<commutative 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 -->